feat(models): add ModelContractPatch and patch validation system (OMN-1126)

docs/guides/CONTRACT_PATCHING_GUIDE.md

@@ -1,7 +1,7 @@
 # Contract Patching Guide
 
-**Version**: 1.0.1
-**Last Updated**: 2025-12-31
+**Version**: 1.0.2
+**Last Updated**: 2026-01-03
 **Status**: Comprehensive Reference
 
 > **New in v0.4.0**: Contract patches provide a declarative way to extend base contracts produced by profile factories. This guide explains the patching system architecture, model reference, and end-to-end usage examples.
@@ -205,7 +205,7 @@ Partial behavior overrides for handler settings. This model is used in the `desc
 ```python
 from omnibase_core.models.contracts.model_descriptor_patch import ModelDescriptorPatch
 
-behavior = ModelDescriptorPatch(
+descriptor = ModelDescriptorPatch(
     purity="pure",                        # "pure" | "side_effecting"
     idempotent=True,                      # Safe to retry?
     timeout_ms=30000,                     # Max execution time
@@ -574,7 +574,7 @@ patch = ModelContractPatch(
     ),
 )
 
-# Verify descriptor overrides
+# Verify behavior overrides
 assert patch.descriptor.timeout_ms == 60000
 assert patch.descriptor.retry_policy.max_retries == 5
 ```
@@ -784,31 +784,33 @@ These run when you call `validator.validate(patch)`:
 
 | Check | Severity | Error Code |
 |-------|----------|------------|
-| Duplicate handlers in `handlers__add` | Error | `DUPLICATE_LIST_ENTRIES` |
-| Duplicate dependencies in `dependencies__add` | Error | `DUPLICATE_LIST_ENTRIES` |
-| Duplicate capabilities in `capability_outputs__add` | Error | `DUPLICATE_LIST_ENTRIES` |
-| Duplicate inputs in `capability_inputs__add` | Error | `DUPLICATE_LIST_ENTRIES` |
-| Empty behavior patch (no overrides) | Warning | `EMPTY_DESCRIPTOR_PATCH` |
-| `purity="pure"` with `idempotent=False` | Warning | `PURITY_IDEMPOTENT_MISMATCH` |
+| Duplicate handlers in `handlers__add` | Error | `CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES` |
+| Duplicate dependencies in `dependencies__add` | Error | `CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES` |
+| Duplicate capabilities in `capability_outputs__add` | Error | `CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES` |
+| Duplicate inputs in `capability_inputs__add` | Error | `CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES` |
+| Duplicate events in `consumed_events__add` | Error | `CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES` |
+| Empty behavior patch (no overrides) | Info | `CONTRACT_PATCH_EMPTY_DESCRIPTOR` |
+| `purity="pure"` with `idempotent=False` | Warning | `CONTRACT_PATCH_PURITY_IDEMPOTENT_MISMATCH` |
+| New contract identity declared | Info | `CONTRACT_PATCH_NEW_IDENTITY` |
 
 #### 3. Format Validation (Warnings)
 
 | Check | Description | Error Code |
 |-------|-------------|------------|
-| Profile Name | Should be lowercase_with_underscores | `NON_STANDARD_PROFILE_NAME` |
-| Version Format | Should contain digits (semver) | `NON_STANDARD_VERSION_FORMAT` |
+| Profile Name | Should be lowercase_with_underscores | `CONTRACT_PATCH_NON_STANDARD_PROFILE_NAME` |
+| Version Format | Should contain digits (semver) | `CONTRACT_PATCH_NON_STANDARD_VERSION_FORMAT` |
 
 #### 4. File Validation Error Codes
 
 When using `validate_file()`:
 
 | Condition | Error Code |
 |-----------|------------|
-| File does not exist | `FILE_NOT_FOUND` |
-| Cannot read file | `FILE_READ_ERROR` |
-| Non-.yaml/.yml extension | `UNEXPECTED_EXTENSION` (warning) |
-| YAML parsing or validation error | `YAML_VALIDATION_ERROR` |
-| Pydantic validation error | `PYDANTIC_VALIDATION_ERROR` |
+| File does not exist | `CONTRACT_PATCH_FILE_NOT_FOUND` |
+| Cannot read file | `CONTRACT_PATCH_FILE_READ_ERROR` |
+| Non-.yaml/.yml extension | `CONTRACT_PATCH_UNEXPECTED_EXTENSION` (warning) |
+| YAML parsing or validation error | `CONTRACT_PATCH_YAML_VALIDATION_ERROR` |
+| Pydantic validation error | `CONTRACT_PATCH_PYDANTIC_VALIDATION_ERROR` |
 
 ### What Is NOT Validated (Deferred)
 
@@ -1028,6 +1030,6 @@ patch = ModelContractPatch(
 
 ---
 
-**Last Updated**: 2025-12-31
-**Version**: 1.0.1
+**Last Updated**: 2026-01-03
+**Version**: 1.0.2
 **Maintainer**: ONEX Framework Team

scripts/validation/validate-string-versions.py

@@ -615,7 +615,7 @@ def validate_python_file(self, python_path: Path) -> bool:
         try:
             tree = ast.parse(content, filename=str(python_path))
             # Pass source lines to enable inline comment bypass checking
-            source_lines = content.split("\n")
+            source_lines = content.splitlines()
             ast_validator = PythonASTValidator(str(python_path), source_lines)
             ast_validator.visit(tree)
 
@@ -642,7 +642,7 @@ def _validate_python_version_declarations(
         errors: list[str],
     ) -> None:
         """Check Python content for hardcoded __version__ declarations."""
-        lines = content.split("\n")
+        lines = content.splitlines()
 
         # Track bypass comments
         bypass_patterns = [
@@ -805,7 +805,7 @@ def _validate_yaml_content_ast(
         errors: list[str],
     ) -> None:
         """Use AST-like parsing to detect string versions in YAML content."""
-        lines = content.split("\n")
+        lines = content.splitlines()
 
         version_field_patterns = [
             "version:",

src/omnibase_core/enums/__init__.py

@@ -177,6 +177,9 @@
 
 # Parameter and return type enums
 from .enum_parameter_type import EnumParameterType
+
+# Patch validation error codes (OMN-1126)
+from .enum_patch_validation_error_code import EnumPatchValidationErrorCode
 from .enum_query_parameter_transformation_type import (
     EnumQueryParameterTransformationType,
 )
@@ -283,6 +286,7 @@
     "EnumCLIExitCode",
     "EnumOnexErrorCode",
     "EnumCoreErrorCode",
+    "EnumPatchValidationErrorCode",
     "EnumRegistryErrorCode",
     "CORE_ERROR_CODE_TO_EXIT_CODE",
     "get_core_error_description",

src/omnibase_core/enums/enum_likelihood.py

@@ -169,8 +169,9 @@ def from_probability(cls, probability: float) -> EnumLikelihood:
             from omnibase_core.errors import ModelOnexError
 
             raise ModelOnexError(
-                f"probability must be between 0.0 and 1.0, got {probability}",
+                message=f"probability must be between 0.0 and 1.0, got {probability}",
                 error_code=EnumCoreErrorCode.VALIDATION_ERROR,
+                probability=probability,
             )
         if probability <= 0.0:
             return cls.IMPOSSIBLE

src/omnibase_core/enums/enum_patch_validation_error_code.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Patch validation error codes for contract patch validation.
+
+These error codes are used by ContractPatchValidator to categorize
+validation issues in contract patches. They provide type-safe
+identification of validation errors and warnings.
+
+Error Code Categories:
+    - List Operations: Duplicate detection within add lists
+    - Descriptor/Behavior: Behavior patch consistency issues
+    - Identity: Contract identity field issues
+    - Profile: Profile reference format issues
+    - File I/O: File access and parsing issues
+    - Validation: General validation errors
+
+Related:
+    - OMN-1126: ModelContractPatch & Patch Validation
+    - ContractPatchValidator: The validator that uses these codes
+
+.. versionadded:: 0.4.0
+"""
+
+from enum import Enum
+
+
+class EnumPatchValidationErrorCode(str, Enum):
+    """Error codes for contract patch validation.
+
+    These codes categorize the types of issues that can be detected
+    during contract patch validation. They are used in validation
+    results to provide machine-readable issue identification.
+
+    All error codes follow the CONTRACT_PATCH_* prefix convention for
+    consistent categorization and type-safe identification per PR #289.
+
+    Attributes:
+        CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES: Duplicate items within an add list
+        CONTRACT_PATCH_EMPTY_DESCRIPTOR: Behavior patch with no overrides
+        CONTRACT_PATCH_PURITY_IDEMPOTENT_MISMATCH: Conflicting purity/idempotent settings
+        CONTRACT_PATCH_NEW_IDENTITY: Informational - new contract identity declared
+        CONTRACT_PATCH_NON_STANDARD_PROFILE_NAME: Profile name doesn't follow conventions
+        CONTRACT_PATCH_NON_STANDARD_VERSION_FORMAT: Version string format is non-standard
+        CONTRACT_PATCH_FILE_NOT_FOUND: File does not exist
+        CONTRACT_PATCH_FILE_READ_ERROR: File could not be read
+        CONTRACT_PATCH_UNEXPECTED_EXTENSION: File has unexpected extension
+        CONTRACT_PATCH_YAML_VALIDATION_ERROR: YAML parsing or validation error
+        CONTRACT_PATCH_PYDANTIC_VALIDATION_ERROR: Pydantic model validation error
+
+    Example:
+        >>> from omnibase_core.enums import EnumPatchValidationErrorCode
+        >>> code = EnumPatchValidationErrorCode.CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES
+        >>> result.add_error("Duplicate handler found", code=code.value)
+    """
+
+    # List operation errors
+    CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES = "CONTRACT_PATCH_DUPLICATE_LIST_ENTRIES"
+    """Duplicate items found within an add list (e.g., handlers__add)."""
+
+    # Descriptor/Behavior errors
+    CONTRACT_PATCH_EMPTY_DESCRIPTOR = "CONTRACT_PATCH_EMPTY_DESCRIPTOR"
+    """Behavior patch (descriptor field) is present but has no overrides."""
+
+    CONTRACT_PATCH_PURITY_IDEMPOTENT_MISMATCH = (
+        "CONTRACT_PATCH_PURITY_IDEMPOTENT_MISMATCH"
+    )
+    """Conflicting purity='pure' with idempotent=False settings."""
+
+    # Identity errors
+    CONTRACT_PATCH_NEW_IDENTITY = "CONTRACT_PATCH_NEW_IDENTITY"
+    """Informational: Patch declares a new contract identity (name + version)."""
+
+    # Profile reference errors
+    CONTRACT_PATCH_NON_STANDARD_PROFILE_NAME = (
+        "CONTRACT_PATCH_NON_STANDARD_PROFILE_NAME"
+    )
+    """Profile name doesn't follow lowercase_with_underscores convention."""
+
+    CONTRACT_PATCH_NON_STANDARD_VERSION_FORMAT = (
+        "CONTRACT_PATCH_NON_STANDARD_VERSION_FORMAT"
+    )
+    """Version string format is non-standard (expected semver-like)."""
+
+    # File I/O errors
+    CONTRACT_PATCH_FILE_NOT_FOUND = "CONTRACT_PATCH_FILE_NOT_FOUND"
+    """The specified file does not exist."""
+
+    CONTRACT_PATCH_FILE_READ_ERROR = "CONTRACT_PATCH_FILE_READ_ERROR"
+    """The file could not be read (I/O error)."""
+
+    CONTRACT_PATCH_UNEXPECTED_EXTENSION = "CONTRACT_PATCH_UNEXPECTED_EXTENSION"
+    """File has unexpected extension (expected .yaml or .yml)."""
+
+    # Validation errors
+    CONTRACT_PATCH_YAML_VALIDATION_ERROR = "CONTRACT_PATCH_YAML_VALIDATION_ERROR"
+    """YAML parsing or validation error occurred."""
+
+    CONTRACT_PATCH_PYDANTIC_VALIDATION_ERROR = (
+        "CONTRACT_PATCH_PYDANTIC_VALIDATION_ERROR"
+    )
+    """Pydantic model validation error occurred."""