feat(contracts): add Handler Contract Model & YAML Schema (OMN-1117)

.gitignore

@@ -30,7 +30,7 @@ sdist/
 wheels/
 *.egg-info/
 *.egg
-MANIFEST
+/MANIFEST
 
 # Legacy packaging formats
 .Python

CHANGELOG.md

@@ -9,6 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### ⚠️ BREAKING CHANGES
 
+#### ModelHandlerBehaviorDescriptor Renamed to ModelHandlerBehavior [OMN-1117]
+
+The `ModelHandlerBehaviorDescriptor` class has been renamed to `ModelHandlerBehavior`. The backwards compatibility shim (`model_handler_behavior_descriptor.py`) and alias have been **removed**.
+
+**Impact**:
+- Code importing `ModelHandlerBehaviorDescriptor` will raise `ImportError`
+- Code importing from `model_handler_behavior_descriptor` will raise `ImportError`
+
+**Migration Guide**:
+
+```python
+# Before (v0.3.x)
+from omnibase_core.models.runtime.model_handler_behavior_descriptor import (
+    ModelHandlerBehaviorDescriptor,
+)
+contract = ModelHandlerContract(
+    descriptor=ModelHandlerBehaviorDescriptor(handler_kind="compute", ...),
+    ...
+)
+
+# After (v0.4.0+)
+from omnibase_core.models.runtime.model_handler_behavior import (
+    ModelHandlerBehavior,
+)
+contract = ModelHandlerContract(
+    descriptor=ModelHandlerBehavior(handler_kind="compute", ...),
+    ...
+)
+```
+
+**Quick Migration**:
+```bash
+# Find affected imports
+grep -rn "ModelHandlerBehaviorDescriptor\|model_handler_behavior_descriptor" --include="*.py"
+
+# Replace in files (Linux/macOS)
+find . -name "*.py" -exec sed -i 's/ModelHandlerBehaviorDescriptor/ModelHandlerBehavior/g' {} \;
+find . -name "*.py" -exec sed -i 's/model_handler_behavior_descriptor/model_handler_behavior/g' {} \;
+```
+
 #### Hook Typing Enforcement Enabled by Default [OMN-1157]
 
 The default value of `BuilderExecutionPlan.enforce_hook_typing` has been changed from `False` to `True`. This is a **fail-fast behavior change** that affects code building execution plans with typed hooks.

docs/INDEX.md

@@ -109,6 +109,7 @@ omnibase_core/docs/
 | [Documentation Architecture](architecture/DOCUMENTATION_ARCHITECTURE.md) | Documentation structure and organization | ✅ Complete |
 | [Subcontract Architecture](architecture/SUBCONTRACT_ARCHITECTURE.md) | Contract system design and subcontract patterns | ✅ Complete |
 | [Mixin Architecture](architecture/MIXIN_ARCHITECTURE.md) | Mixin system design and patterns | ✅ Complete |
+| [**Mixins to Handlers Refactor**](architecture/MIXINS_TO_HANDLERS_REFACTOR.md) | Handler-based architecture, manifest spec, replay invariants ⭐ **BETA** | ✅ Draft |
 | [Protocol Architecture](architecture/PROTOCOL_ARCHITECTURE.md) | Protocol design and compliance | ✅ Complete |
 | [Effect Timeout Behavior](architecture/EFFECT_TIMEOUT_BEHAVIOR.md) | Timeout check points and retry behavior | ✅ Complete |
 | [Ecosystem Directory Structure](architecture/ECOSYSTEM_DIRECTORY_STRUCTURE.md) | Repository organization and patterns across ONEX ecosystem | ✅ Available |
@@ -287,6 +288,7 @@ def serialize_error(error: ModelOnexError) -> TypedDictValidationErrorSerialized
 | Document | Description | Status |
 |----------|-------------|--------|
 | [**Subcontract Architecture**](architecture/SUBCONTRACT_ARCHITECTURE.md) | Contract system design | ✅ Excellent |
+| [**Handler Contract Guide**](contracts/HANDLER_CONTRACT_GUIDE.md) | Handler contract authoring, ID prefix convention | ✅ Complete |
 | [Approved Union Patterns](patterns/APPROVED_UNION_PATTERNS.md) | Type union patterns | ✅ Available |
 
 ### Project Documentation
@@ -322,6 +324,7 @@ def serialize_error(error: ModelOnexError) -> TypedDictValidationErrorSerialized
 | **Fix slow performance tests** | [Performance Benchmark Thresholds](performance/PERFORMANCE_BENCHMARK_THRESHOLDS.md#ci-performance-degradation) |
 | **Debug async hangs** | [Async Hang Debugging](troubleshooting/ASYNC_HANG_DEBUGGING.md) |
 | **Understand contracts** | [Subcontract Architecture](architecture/SUBCONTRACT_ARCHITECTURE.md) |
+| **Create handler contracts** | [Handler Contract Guide](contracts/HANDLER_CONTRACT_GUIDE.md) |
 | **Use TypedDict for serialization** | [TypedDict Types](#typeddict-types-serialization-boundaries) - Strongly-typed serialization boundaries |
 | **Validate mixin metadata** | [ModelMixinMetadata](../src/omnibase_core/models/core/model_mixin_metadata.py) - Mixin discovery & validation |
 | **Validate docker-compose.yaml** | [ModelDockerComposeManifest](../src/omnibase_core/models/docker/model_docker_compose_manifest.py) - Docker validation |

docs/architecture/EXECUTION_SHAPE_EXAMPLES.md

@@ -657,7 +657,7 @@ Use **Command to Effect** when:
 
 ```python
 from typing import Any
-from datetime import datetime
+from datetime import datetime, timezone
 
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel
@@ -761,7 +761,7 @@ async def health_check() -> HealthResponse:
         status=status,
         database=results["database"],
         cache=results["cache"],
-        timestamp=datetime.utcnow().isoformat()
+        timestamp=datetime.now(timezone.utc).isoformat()
     )