[jonahgabriel]

Summary

• Rename handler_kind field to node_archetype across omnibase_core
• Align with omnibase_infra PR refactor(nodes): replace print statements with structured logging [OMN-701] #187 for cross-repo consistency
• Establish canonical vocabulary for contract-level architectural roles

Changes

New Files

• src/omnibase_core/enums/enum_node_archetype.py - New enum with COMPUTE, EFFECT, REDUCER, ORCHESTRATOR values

Core Model Updates

• ModelHandlerBehavior: Field renamed with NodeArchetypeField type alias (includes BeforeValidator for YAML string coercion)
• ModelHandlerContract: Validator renamed to validate_descriptor_node_archetype_consistency
• JSON schema updated with node_archetype property

Factory & Validation Updates

• All profile factories use EnumNodeArchetype.X enum values
• validator_expanded_contract.py: Method renamed
• contract_merge_engine.py: Uses enum values
• handler_contract_validator.py script: Complete update

Documentation & Examples

• 4 documentation files updated (45 occurrences total)
• 4 YAML example contracts updated
• 15 test files updated

Breaking Change

Contracts must use node_archetype instead of handler_kind. The schema hard-rejects handler_kind - no backwards compatibility per ONEX "break now, no shims" policy.

# Before
descriptor:
  handler_kind: compute

# After
descriptor:
  node_archetype: compute

Test plan

• 109 core tests pass (handler contract, factory, merge, validation)
• mypy passes on all updated files
• All pre-commit hooks pass
• No handler_kind references remain (except changelog docs)
• Example contracts validate with new schema

Related

• Linear ticket: OMN-1465
• Blocking: omnibase_infra PR refactor(nodes): replace print statements with structured logging [OMN-701] #187 integration tests
• Parent: OMN-1095 (Handler Source Mode Feature Flag)

Summary by CodeRabbit

• Documentation

  • Updated guides, examples, schema docs, and error messages to use the term "node_archetype" instead of "handler_kind".

• Refactor

  • Renamed public descriptor field from handler_kind to node_archetype and introduced a typed enum for archetype values (compute, effect, reducer, orchestrator).
  • Validation and messaging updated to reflect the new terminology.

• Chores

  • Package version bumped to 0.9.2.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR renames the public field handler_kind to node_archetype across the codebase, adds EnumNodeArchetype, and updates all related models, validators, schemas, factory profiles, docs, examples, tests, and merge/validation logic to use the new name and enum.

Changes

Cohort / File(s)	Summary
Core Enum Definition src/omnibase_core/enums/enum_node_archetype.py, src/omnibase_core/enums/__init__.py	Added EnumNodeArchetype and re-exported it in the enums package.
Model Runtime src/omnibase_core/models/runtime/model_handler_behavior.py	Renamed handler_kind → node_archetype; added NodeArchetypeField, coercion, and updated docstrings and all.
Model Contracts & Validation src/omnibase_core/models/contracts/model_handler_contract.py, scripts/validation/handler_contract_validator.py, src/omnibase_core/validation/phases/validator_expanded_contract.py	Replaced descriptor references and validation methods from handler_kind → node_archetype; updated validators, error payload keys, and internal mappings (prefix_to_kind → prefix_to_archetype).
Factory Profiles src/omnibase_core/factories/profiles/factory_profile_*.py (compute, effect, orchestrator, reducer)	Updated profiles to use node_archetype=EnumNodeArchetype.* and added enum imports; some profiles expanded effect config.
Merge Engine src/omnibase_core/merge/contract_merge_engine.py	Propagates node_archetype in merge/default behavior instead of handler_kind; added enum import.
Protocol & Resolution src/omnibase_core/protocols/resolution/protocol_execution_resolver.py	Updated examples and docstrings to construct ModelHandlerBehavior with node_archetype instead of handler_kind.
Schema src/omnibase_core/schemas/handler_contract.schema.json	Replaced handler_kind property with node_archetype, updated titles, descriptions, required lists, and See Also to EnumNodeArchetype.
Validators (scripts) scripts/validation/handler_contract_validator.py	Renamed validator classes/fields to reference node_archetype, introduced MinimalNodeArchetype and updated validation logic/messages.
Docs & Guides docs/architecture/MIXINS_TO_HANDLERS_REFACTOR.md, docs/contracts/HANDLER_CONTRACT_GUIDE.md, docs/guides/CONTRACT_PATCHING_GUIDE.md, docs/guides/CONTRACT_PROFILE_GUIDE.md	Replaced terminology and examples from handler_kind → node_archetype throughout.
Examples & YAMLs examples/contracts/handlers/*.yaml, examples/demo/handlers/support_assistant/support_assistant.yaml	Updated descriptor keys from handler_kind → node_archetype.
Tests — Unit & Integration tests/unit/**, tests/integration/** (many files listed in diff)	Updated all test fixtures, constructor calls, assertions, and test names to use node_archetype; aligned expected error messages and mappings.
Packaging pyproject.toml, src/omnibase_core/__init__.py	Bumped project version from 0.9.1 → 0.9.2.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat(factories): add default profile factory for contracts (OMN-1125) #284: Modifies profile factories and contract descriptor usage in the same areas affected by the handler_kind → node_archetype rename.
• feat(resolution): add ExecutionResolver for pure execution order resolution (OMN-1106) #307: Updates usages in protocol resolution examples; overlaps the same ModelHandlerBehavior constructor rename.

Poem

🐰 I hopped through files both near and far,

handler_kind buried beneath a new star,
node_archetype crowned with enum delight,
Validators tuned and tests set aright,
A tiny rabbit cheers the refactor night.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: renaming handler_kind to node_archetype across the codebase, with a reference to the tracking issue OMN-1465.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/omnibase_core/schemas/handler_contract.schema.json`:
- Line 262: Update the stale enum reference in the long description string:
replace the "See Also" entry that mentions EnumNodeKind with EnumNodeArchetype
and update its brief text to "Enum defining node archetype values" so the
description matches the renamed symbol; look for the description field in
handler_contract.schema.json (the block containing "See Also:") and change the
EnumNodeKind reference to EnumNodeArchetype.

🧹 Nitpick comments (1)

src/omnibase_core/models/contracts/model_handler_contract.py (1)

46-59: Prefer EnumNodeArchetype constants in the prefix map to avoid string drift.

Using enum values keeps the mapping aligned with the canonical set and reduces typo risk in future edits.

♻️ Suggested refactor

-from omnibase_core.enums.enum_core_error_code import EnumCoreErrorCode
+from omnibase_core.enums.enum_core_error_code import EnumCoreErrorCode
+from omnibase_core.enums.enum_node_archetype import EnumNodeArchetype
@@
-        # Map common prefixes to node archetypes
-        prefix_to_archetype = {
-            "node": None,  # Generic, any archetype allowed
-            "handler": None,  # Generic, any archetype allowed
-            "compute": "compute",
-            "effect": "effect",
-            "reducer": "reducer",
-            "orchestrator": "orchestrator",
-        }
+        # Map common prefixes to node archetypes
+        prefix_to_archetype = {
+            "node": None,  # Generic, any archetype allowed
+            "handler": None,  # Generic, any archetype allowed
+            "compute": EnumNodeArchetype.COMPUTE,
+            "effect": EnumNodeArchetype.EFFECT,
+            "reducer": EnumNodeArchetype.REDUCER,
+            "orchestrator": EnumNodeArchetype.ORCHESTRATOR,
+        }
@@
-        # EnumNodeArchetype inherits from str, so string comparison works
-        if (
-            expected_archetype is not None
-            and str(self.descriptor.node_archetype) != expected_archetype
-        ):
+        # EnumNodeArchetype inherits from str, so direct comparison works
+        if expected_archetype is not None and self.descriptor.node_archetype != expected_archetype:
             raise ModelOnexError(
                 message=(
                     f"Handler ID prefix '{prefix}' implies node_archetype='{expected_archetype}' "
                     f"but descriptor has node_archetype='{self.descriptor.node_archetype}'"
                 ),
                 error_code=EnumCoreErrorCode.VALIDATION_ERROR,
                 handler_id=self.handler_id,
-                expected_archetype=expected_archetype,
+                expected_archetype=str(expected_archetype),
                 actual_archetype=str(self.descriptor.node_archetype),
             )

Also applies to: 364-404