feat(models): implement ModelOnexEnvelope unified message format [OMN-224]

.pre-commit-config.yaml

@@ -282,6 +282,21 @@ repos:
         exclude: ^(tests/|archived/|archive/|scripts/validation/).*\.py$
         stages: [pre-commit]
 
+      # dict[str, Any] Anti-Pattern Detection
+      # Enforces strong typing by detecting dict[str, Any] usage
+      # TECHNICAL DEBT: Current baseline is 842 violations (2025-12-05)
+      # Goal: Reduce to 0 over time by replacing with TypedDict or specific models
+      # Track progress by lowering --max-violations as fixes are applied
+      - id: validate-dict-any-usage
+        name: ONEX dict[str, Any] Anti-Pattern Detection
+        entry: poetry run python scripts/validation/validate-dict-any-usage.py
+        args: [--max-violations, "850"]
+        language: system
+        pass_filenames: false
+        files: ^src/.*\.py$
+        exclude: ^(tests/|archived/|archive/|scripts/validation/).*\.py$
+        stages: [pre-commit]
+
       - id: no-pydantic-bypass-in-prod
         name: ONEX Pydantic Bypass Prevention
         entry: poetry run python scripts/validation/validate-no-pydantic-bypass.py

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Renamed `ModelOnexEnvelopeV1` to `ModelOnexEnvelope` (OMN-224)
+- Renamed fields: `event_id`→`envelope_id`, `source_service`→`source_node`, `event_type`→`operation`
+- Added new fields: `causation_id`, `target_node`, `handler_type`, `metadata`, `is_response`, `success`, `error`
+
 ## [0.3.3] - 2025-11-19
 
 ### Added
@@ -85,7 +90,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Node Introspection Improvements
 - **ONEX Architecture Classification**: Added `node_type` field with 4-node validation (effect, compute, reducer, orchestrator) to `ModelNodeIntrospectionEvent`
 - **Node Role Support**: Added optional `node_role` field for specialization within node types
-- **Source Node Tracking**: Added `source_node_id` field to `ModelOnexEnvelopeV1` for node-to-node event correlation and tracking
+- **Source Node Tracking**: Added `source_node_id` field to `ModelOnexEnvelopeV1` for node-to-node event correlation and tracking (Note: `ModelOnexEnvelopeV1` was later renamed to `ModelOnexEnvelope` in OMN-224)
 
 #### Documentation Enhancements
 - **Mermaid Diagrams**: Added 5 visual diagrams for ONEX architecture flows:

docs/INDEX.md

@@ -147,13 +147,11 @@ omnibase_core/docs/
 | [Configuration Management](patterns/CONFIGURATION_MANAGEMENT.md) | Config patterns | ✅ Available |
 | [Performance Benchmarks](guides/PERFORMANCE_BENCHMARKS.md) | Performance testing | ✅ Available |
 
-### Release Notes
+### Changelog
 
 | Document | Description | Status |
 |----------|-------------|--------|
-| Release Notes v0.2.0 | Discovery enhancements, omnibase_spi v0.2.0 upgrade, container types documentation | ✅ Current |
-| [Release Notes v0.1.1](release-notes/RELEASE_NOTES_v0.1.1.md) | Quality & documentation improvements | ✅ Available |
-| [Release Notes v0.1.0](release-notes/RELEASE_NOTES_v0.1.0.md) | Initial public release | ✅ Available |
+| [CHANGELOG.md](../CHANGELOG.md) | All notable changes following [Keep a Changelog](https://keepachangelog.com) format | ✅ Current |
 
 ---
 

docs/MVP_PLAN.md

@@ -9,6 +9,26 @@
 
 ## Executive Summary
 
+### Current Status (as of 2025-12-05)
+
+| Phase | Complete | Partial | Not Started | Total |
+|-------|----------|---------|-------------|-------|
+| Phase 0: Repository Stabilization | 2 | 2 | 5 | 9 |
+| Phase 1: Legacy Node Migration | 0 | 0 | 5 | 5 |
+| Phase 2: Declarative Node Promotion | 1 | 1 | 5 | 7 |
+| Phase 3-7 | 0 | 0 | 36 | 36 |
+| Future (F.5 RUNTIME_HOST) | 1 | 0 | 13 | 14 |
+| **Total** | **4** | **3** | **64** | **71** |
+
+**Key Completions**:
+- ✅ OMN-222: EnumNodeKind with RUNTIME_HOST value (PR #108)
+- ✅ OMN-223: EnumHandlerType enum for protocol handlers
+- ✅ OMN-224: ModelOnexEnvelope unified message format (PR #112) - In Progress
+- ✅ OMN-232: Core error hierarchy (RuntimeHostError, HandlerExecutionError, etc.)
+- ✅ OMN-241: Contract Linter CLI (omniintelligence)
+- ✅ Pre-refactor API snapshot tests (4 test files in `tests/unit/api_snapshots/`)
+- ✅ NodeCoreBase interface frozen (interface tests + documentation)
+
 ### What v0.4.0 Changes
 - Legacy nodes moved to `nodes/legacy/` namespace with deprecation warnings
 - Declarative nodes become the default exports
@@ -494,11 +514,11 @@ Before ANY refactoring begins, establish a stable baseline that prevents silent
 Lock current public API behavior with snapshot tests before any changes.
 
 **Acceptance Criteria**:
-- [ ] All public exports from `omnibase_core.nodes` captured
-- [ ] All public exports from `omnibase_core.infrastructure` captured
-- [ ] Snapshot tests verify import paths work
-- [ ] Snapshot tests verify class instantiation signatures
-- [ ] CI runs snapshot tests on every PR
+- [x] All public exports from `omnibase_core.nodes` captured
+- [x] All public exports from `omnibase_core.infrastructure` captured
+- [x] Snapshot tests verify import paths work
+- [x] Snapshot tests verify class instantiation signatures
+- [x] CI runs snapshot tests on every PR
 - [ ] If snapshot tests fail due to intentional breaking changes, they MUST be updated in the same PR with a migration note in the changelog
 
 ---
@@ -514,11 +534,11 @@ Lock current public API behavior with snapshot tests before any changes.
 Create integration tests that verify current node behavior before refactoring.
 
 **Acceptance Criteria**:
-- [ ] NodeCompute behavior captured in tests
-- [ ] NodeEffect behavior captured in tests
+- [x] NodeCompute behavior captured in tests
+- [x] NodeEffect behavior captured in tests
 - [ ] NodeReducer behavior captured in tests
 - [ ] NodeOrchestrator behavior captured in tests
-- [ ] Tests use real container injection
+- [x] Tests use real container injection
 - [ ] Tests pass before AND after refactoring
 
 ---
@@ -579,10 +599,10 @@ Add CI rules that will catch architectural violations during and after refactori
 Document and freeze `NodeCoreBase` interface. Determine if it needs splitting into base logic vs contract-based logic.
 
 **Acceptance Criteria**:
-- [ ] `NodeCoreBase` public methods documented
-- [ ] Decision made: single class vs split architecture
-- [ ] Interface tests created
-- [ ] Breaking changes identified and documented
+- [x] `NodeCoreBase` public methods documented
+- [x] Decision made: single class vs split architecture
+- [x] Interface tests created
+- [x] Breaking changes identified and documented
 
 ---
 
@@ -1017,12 +1037,12 @@ def __getattr__(name: str):
 Update `EnumNodeKind` enum with any new values needed, create compatibility mapping for legacy->declarative names.
 
 **Acceptance Criteria**:
-- [ ] `EnumNodeKind` enum reviewed for completeness
-- [ ] Legacy name → new name mapping created
-- [ ] Serializer/deserializer updated for backward compatibility
+- [x] `EnumNodeKind` enum reviewed for completeness
+- [x] Legacy name → new name mapping created
+- [x] Serializer/deserializer updated for backward compatibility
 - [ ] Legacy→declarative compatibility fingerprint added
-- [ ] mypy --strict passes
-- [ ] Unit tests for enum serialization
+- [x] mypy --strict passes
+- [x] Unit tests for enum serialization
 
 ---
 
@@ -2015,6 +2035,7 @@ Move `MixinDiscovery`, `MixinServiceRegistry`, `MixinCLIHandler` implementations
 **Type**: Feature
 **Priority**: Low (4)
 **Labels**: `architecture`, `new-feature`
+**Status**: ✅ COMPLETE - RUNTIME_HOST enum value added to EnumNodeKind in `src/omnibase_core/enums/enum_node_kind.py`
 
 ---
 

docs/performance/SOURCE_NODE_ID_BENCHMARKS.md

@@ -10,7 +10,7 @@
 
 ## Executive Summary
 
-Performance benchmarks were conducted to measure the overhead introduced by the optional `source_node_id` field added to `ModelOnexEnvelopeV1` in PR #71. This field enables node-to-node event tracking in the ONEX architecture.
+Performance benchmarks were conducted to measure the overhead introduced by the optional `source_node_id` field added to `ModelOnexEnvelope` (formerly `ModelOnexEnvelopeV1`) in PR #71. This field enables node-to-node event tracking in the ONEX architecture.
 
 **Key Findings**:
 - ✅ **Memory overhead**: Zero (0 bytes)
@@ -36,17 +36,20 @@ Performance benchmarks were conducted to measure the overhead introduced by the
 
 ### What is source_node_id?
 
-The `source_node_id` field is an optional UUID field added to `ModelOnexEnvelopeV1` to enable node-to-node event tracking in distributed ONEX workflows.
+The `source_node_id` field is an optional UUID field added to `ModelOnexEnvelope` (formerly `ModelOnexEnvelopeV1`) to enable node-to-node event tracking in distributed ONEX workflows.
 
-```
-class ModelOnexEnvelopeV1(BaseModel):
+```python
+class ModelOnexEnvelope(BaseModel):
     # ... other fields ...
     source_node_id: UUID | None = Field(
         default=None,
-        description="UUID of the node instance that generated this event"
+        description="UUID of the node instance that created this envelope. "
+        "Used for node-to-node tracking in distributed systems.",
     )
 ```
 
+> **Migration Note**: The **model class** `ModelOnexEnvelopeV1` was renamed to `ModelOnexEnvelope` in OMN-224. The `source_node_id` field (optional UUID for tracking node instances) remains unchanged. Note that `source_node_id` is distinct from `source_node`, which is a required string field for the node name.
+
 ### Purpose
 
 - **Node-to-node tracking**: Identify which specific node instance generated an event
@@ -106,7 +109,7 @@ PR #71 reviewer requested benchmarks to quantify:
 
 **Test**: Envelope creation time with and without `source_node_id`
 
-```
+```text
 Creation Time Benchmark:
   Without source_node_id: 0.0060ms ± 0.0001ms
   With source_node_id:    0.0079ms ± 0.0001ms
@@ -128,7 +131,7 @@ Creation Time Benchmark:
 
 **Test**: Dictionary serialization performance
 
-```
+```text
 model_dump() Serialization Benchmark:
   Without source_node_id: 0.0013ms ± 0.0000ms
   With source_node_id:    0.0014ms ± 0.0000ms
@@ -149,7 +152,7 @@ model_dump() Serialization Benchmark:
 
 **Test**: JSON string serialization performance
 
-```
+```text
 model_dump_json() Serialization Benchmark:
   Without source_node_id: 0.0019ms ± 0.0000ms
   With source_node_id:    0.0021ms ± 0.0001ms
@@ -170,7 +173,7 @@ model_dump_json() Serialization Benchmark:
 
 **Test**: Object size and serialized size impact
 
-```
+```text
 Memory Footprint Benchmark:
   Without source_node_id: 72 bytes
   With source_node_id:    72 bytes
@@ -219,7 +222,7 @@ Serialized JSON Size:
 
 **Test**: Serializing 1,000 envelopes to JSON
 
-```
+```text
 Bulk Serialization Benchmark (n=1000):
   Without source_node_id: 0.0043s
   With source_node_id:    0.0022s
@@ -240,7 +243,7 @@ Bulk Serialization Benchmark (n=1000):
 
 **Test**: Complete cycle (create → serialize → deserialize)
 
-```
+```text
 Round Trip Benchmark:
   Without source_node_id: 0.0116ms ± 0.0003ms
   With source_node_id:    0.0137ms ± 0.0001ms
@@ -261,7 +264,7 @@ Round Trip Benchmark:
 
 **Test**: Process-level memory usage at scale (1,000 envelopes)
 
-```
+```text
 Process Memory Benchmark (n=1000):
   Baseline memory:        104.22MB
   After without:          104.22MB (+0.00KB)
@@ -283,7 +286,7 @@ Process Memory Benchmark (n=1000):
 
 **Test**: Baseline performance requirements
 
-```
+```text
 Baseline Creation Performance:
   Average time: 0.0081ms
   Baseline:     1.0000ms
@@ -446,7 +449,7 @@ If overhead becomes a concern (unlikely):
 
 ### Execute All Benchmarks
 
-```
+```bash
 # Run complete benchmark suite
 poetry run pytest tests/performance/test_source_node_id_overhead.py -v
 
@@ -485,7 +488,7 @@ Tests validate against these thresholds:
 ### Re-running Benchmarks
 
 Benchmarks should be re-run:
-- **After major changes** to `ModelOnexEnvelopeV1`
+- **After major changes** to `ModelOnexEnvelope`
 - **Before releases** to detect regressions
 - **On different hardware** to validate portability
 - **Under load** to measure real-world impact
@@ -496,7 +499,7 @@ Benchmarks should be re-run:
 
 ### Test File Location
 
-```
+```text
 tests/performance/test_source_node_id_overhead.py
 ```
 
@@ -508,8 +511,8 @@ tests/performance/test_source_node_id_overhead.py
 ### Key Test Functions
 
 - `time_operation()`: High-precision timing with warmup
-- `create_envelope_without_source_node()`: Baseline envelope creation
-- `create_envelope_with_source_node()`: Overhead envelope creation
+- `create_envelope_without_source_node_id()`: Baseline envelope creation
+- `create_envelope_with_source_node_id()`: Overhead envelope creation
 
 ### Dependencies
 
@@ -530,10 +533,10 @@ tests/performance/test_source_node_id_overhead.py
 
 ## References
 
-- **PR #71**: Added `source_node_id` field to ModelOnexEnvelopeV1
+- **PR #71**: Added `source_node_id` field to `ModelOnexEnvelopeV1` (Note: Model class renamed to `ModelOnexEnvelope` in OMN-224; the `source_node_id` field remains unchanged)
 - **Commit**: 28b0f4df - Implementation commit
 - **Correlation ID**: 95cac850-05a3-43e2-9e57-ccbbef683f43
-- **Model**: `src/omnibase_core/models/core/model_onex_envelope_v1.py`
+- **Model**: `src/omnibase_core/models/core/model_onex_envelope.py` (formerly `model_onex_envelope_v1.py`)
 - **Tests**: `tests/performance/test_source_node_id_overhead.py`
 
 ---