omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/enums/enum_handler_source_type.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Source Type Enumeration for Validation Error Identification.
+
+Defines the canonical source types for handler validation errors in the ONEX
+structured validation and error reporting system. Each source type identifies
+where in the validation pipeline an error was detected, enabling precise
+error attribution and targeted remediation.
+
+Handler validation occurs across multiple stages:
+    - CONTRACT: Error from contract.yaml parsing/validation.
+                Issues with YAML structure, required fields, or schema violations.
+    - DESCRIPTOR: Error from handler descriptor validation.
+                  Issues with handler metadata, signatures, or interface compliance.
+    - STATIC_ANALYSIS: Error from AST/static code analysis.
+                       Issues detected by analyzing Python source without execution.
+    - RUNTIME: Error detected during runtime execution.
+               Issues that only manifest when the handler is invoked.
+    - REGISTRATION: Error during handler registration phase.
+                    Issues with handler registration process or registry state.
+    - CONFIGURATION: Error in handler configuration loading.
+                     Issues with configuration values, environment, or dependencies.
+
+See Also:
+    - EnumHandlerType: Defines handler types (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)
+    - EnumExecutionShapeViolation: Defines validation violation types
+    - ModelHandlerValidationError: Error model that uses this enum for source attribution
+"""
+
+from enum import Enum
+
+
+class EnumHandlerSourceType(str, Enum):
+    """Handler validation error source types for structured error reporting.
+
+    These represent the validation stages where handler errors can be detected.
+    Each source type enables precise error attribution and provides context for
+    debugging and remediation.
+
+    Attributes:
+        CONTRACT: Error from contract.yaml parsing or validation.
+            Indicates issues with the contract definition itself, such as:
+            - Invalid YAML syntax
+            - Missing required fields
+            - Schema validation failures
+            - Invalid handler routing configuration
+        DESCRIPTOR: Error from handler descriptor validation.
+            Indicates issues with handler metadata or interface compliance:
+            - Invalid handler signatures
+            - Missing required methods
+            - Protocol implementation issues
+            - Type annotation problems
+        STATIC_ANALYSIS: Error from AST or static code analysis.
+            Indicates issues detected by analyzing source code without execution:
+            - Forbidden API usage
+            - Invalid import statements
+            - Code structure violations
+            - Purity constraint violations
+        RUNTIME: Error detected during runtime execution.
+            Indicates issues that only manifest when handler is invoked:
+            - Unhandled exceptions
+            - Type mismatches at runtime
+            - Resource exhaustion
+            - Integration failures
+        REGISTRATION: Error during handler registration phase.
+            Indicates issues with the registration process:
+            - Duplicate handler registration
+            - Registry state conflicts
+            - Dependency resolution failures
+            - Handler initialization errors
+        CONFIGURATION: Error in handler configuration loading.
+            Indicates issues with configuration or environment:
+            - Missing environment variables
+            - Invalid configuration values
+            - Dependency injection failures
+            - Service connection issues
+    """
+
+    CONTRACT = "contract"
+    DESCRIPTOR = "descriptor"
+    STATIC_ANALYSIS = "static_analysis"
+    RUNTIME = "runtime"
+    REGISTRATION = "registration"
+    CONFIGURATION = "configuration"
+
+
+__all__ = ["EnumHandlerSourceType"]

omnibase_infra/enums/enum_handler_type.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Type Enumeration - Architectural Role Classification.
+
+Defines the architectural role of handlers in the ONEX system.
+Each handler type drives lifecycle management, protocol selection, and runtime
+invocation pattern. This is orthogonal to behavioral classification (EnumHandlerTypeCategory).
+
+Architectural Role Semantics:
+    - INFRA_HANDLER: Protocol/transport handlers that manage external connections.
+        Examples: HTTP adapters, database connectors, Consul clients, Vault clients.
+        Lifecycle: Connection pooling, health checks, circuit breakers.
+    - NODE_HANDLER: Event processing handlers bound to ONEX nodes.
+        Examples: Effect handlers, orchestrator step handlers.
+        Lifecycle: Node registration, event subscription, capability advertisement.
+    - PROJECTION_HANDLER: Handlers for projection read/write operations.
+        Examples: State projection writers, read model updaters.
+        Lifecycle: Projection versioning, consistency guarantees.
+    - COMPUTE_HANDLER: Pure computation handlers with no side effects.
+        Examples: Validation handlers, transformation handlers.
+        Lifecycle: Stateless, idempotent, cacheable.
+
+Design Principle:
+    Handler descriptors must specify BOTH:
+    1. EnumHandlerType (architectural role - this enum)
+    2. EnumHandlerTypeCategory (behavioral classification)
+
+    This separation enables:
+    - Architectural role: Drives infrastructure binding and lifecycle
+    - Behavioral category: Drives execution shape validation and output constraints
+
+See Also:
+    - EnumHandlerTypeCategory: Behavioral classification (EFFECT, COMPUTE, NONDETERMINISTIC_COMPUTE)
+    - EnumNodeArchetype: Node archetypes for execution shape validation
+    - EnumNodeOutputType: Valid node output types
+    - EnumMessageCategory: Message categories for routing
+    - HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md: Full handler architecture documentation
+"""
+
+from enum import Enum
+
+
+class EnumHandlerType(str, Enum):
+    """Handler architectural role - selects interface and lifecycle.
+
+    These represent the architectural classification of handlers in ONEX.
+    Each type drives lifecycle management, protocol selection, and runtime invocation pattern.
+
+    Note: This is orthogonal to EnumHandlerTypeCategory which represents behavioral classification.
+    Both must be specified on handler descriptors.
+
+    Attributes:
+        INFRA_HANDLER: Protocol/transport handlers (HTTP, DB, Consul, Vault).
+            Manages external connections and protocol-specific operations.
+            Lifecycle: Connection pooling, health checks, circuit breakers.
+            Examples: DatabaseAdapter, ConsulClient, VaultClient, HttpGateway.
+        NODE_HANDLER: Event processing handlers bound to nodes.
+            Handles event routing and processing within the ONEX node graph.
+            Lifecycle: Node registration, event subscription, capability advertisement.
+            Examples: RegistrationHandler, IntrospectionHandler, RoutingHandler.
+        PROJECTION_HANDLER: Projection read/write handlers.
+            Manages projection state and read model operations.
+            Lifecycle: Projection versioning, consistency guarantees, snapshot management.
+            Examples: StateProjectionWriter, ReadModelUpdater, SnapshotHandler.
+        COMPUTE_HANDLER: Pure computation handlers.
+            Performs stateless, deterministic transformations.
+            Lifecycle: Stateless, idempotent, cacheable - no external dependencies.
+            Examples: ValidationHandler, TransformationHandler, SerializationHandler.
+    """
+
+    INFRA_HANDLER = "infra_handler"
+    NODE_HANDLER = "node_handler"
+    PROJECTION_HANDLER = "projection_handler"
+    COMPUTE_HANDLER = "compute_handler"
+
+
+__all__ = ["EnumHandlerType"]

omnibase_infra/enums/enum_handler_type_category.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Type Category Enumeration for behavioral classification.
+
+Defines the behavioral classification of handlers for ONEX architecture.
+This enum is orthogonal to EnumHandlerType (architectural role) - both must
+be specified on handler descriptors.
+
+Classification Guide:
+    | Category | Deterministic? | Side Effects? | Examples |
+    |----------|----------------|---------------|----------|
+    | COMPUTE | Yes | No | Validation, transformation, mapping |
+    | EFFECT | N/A | Yes | DB, HTTP, Consul, Vault, Kafka, LLM calls |
+    | NONDETERMINISTIC_COMPUTE | No | No | UUID generation, datetime.now(), random.choice() |
+
+Note: LLM API calls are EFFECT (external I/O), not NONDETERMINISTIC_COMPUTE.
+
+See Also:
+    - EnumHandlerType: Architectural role classification (INFRA_HANDLER, NODE_HANDLER, etc.)
+    - EnumNodeArchetype: Node archetypes for execution shape validation (EFFECT, COMPUTE, etc.)
+    - HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md: Full architecture documentation
+
+Note on Naming Consistency:
+    EnumHandlerTypeCategory and EnumNodeArchetype both use EFFECT and COMPUTE values but serve
+    different purposes:
+    - EnumHandlerTypeCategory: Classifies handler BEHAVIOR (side effects, determinism)
+    - EnumNodeArchetype: Classifies node ARCHITECTURE (execution shape validation)
+    The shared terminology reflects that EFFECT handlers are typically bound to EFFECT nodes,
+    and COMPUTE handlers to COMPUTE nodes, but they represent different conceptual axes.
+"""
+
+from enum import Enum
+
+
+class EnumHandlerTypeCategory(str, Enum):
+    """Handler behavioral classification - selects policy envelope.
+
+    Determines how the handler behaves at runtime and what policies apply.
+    Drives: Security rules, determinism guarantees, replay safety, permissions.
+
+    Note: ADAPTER is NOT a category - it's a policy tag (is_adapter: bool) on
+    handler descriptors. Adapters are behaviorally EFFECT but have stricter defaults.
+
+    Attributes:
+        COMPUTE: Pure, deterministic computation. No side effects.
+            Examples: Validation, transformation, mapping, calculations.
+            Safe for replay, caching, and parallel execution.
+        EFFECT: Side-effecting I/O operations. May not be deterministic.
+            Examples: Database operations, HTTP calls, Consul, Vault, Kafka, LLM APIs.
+            Requires idempotency handling for replay safety.
+        NONDETERMINISTIC_COMPUTE: Pure (no I/O) but not deterministic.
+            Examples: UUID generation, datetime.now(), random.choice().
+            No external side effects but results may vary between runs.
+    """
+
+    COMPUTE = "compute"
+    EFFECT = "effect"
+    NONDETERMINISTIC_COMPUTE = "nondeterministic_compute"
+
+
+__all__ = ["EnumHandlerTypeCategory"]

omnibase_infra/enums/enum_infra_transport_type.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Infrastructure Transport Type Enumeration.
+
+Defines the canonical transport types for infrastructure components.
+Used for error context, protocol routing, and transport identification.
+
+Supported transport types:
+    - HTTP: REST API transport
+    - DATABASE: PostgreSQL and other database connections
+    - KAFKA: Kafka message broker
+    - CONSUL: Consul service discovery and KV operations
+    - VAULT: HashiCorp Vault secret management
+    - VALKEY: Valkey (Redis-compatible) cache/messaging
+    - GRPC: gRPC protocol
+    - RUNTIME: Runtime host internal transport
+    - MCP: Model Context Protocol (AI agent tool interface)
+    - FILESYSTEM: Local filesystem operations
+    - INMEMORY: In-memory transport for testing/local development
+    - QDRANT: Qdrant vector database operations
+    - GRAPH: Graph database (Memgraph/Neo4j) operations
+
+Each transport type has a corresponding handler implementation:
+    - HandlerConsul: Service registration, health checks, KV store operations
+    - HandlerVault: Secret retrieval, token management, lease renewal
+    - EventBusKafka: Event publishing/subscription, consumer groups
+    - EventBusInmemory: In-memory event bus for testing and local development
+    - PostgresConnectionManager: Connection pooling, query execution
+    - HandlerMCP: MCP server for exposing ONEX nodes as AI agent tools
+    - HandlerFileSystem: File read/write, directory operations
+"""
+
+from enum import Enum
+
+
+class EnumInfraTransportType(str, Enum):
+    """Infrastructure transport types for ONEX infrastructure components.
+
+    These represent the transport/protocol layer types used in
+    omnibase_infra for external integration.
+
+    Attributes:
+        HTTP: HTTP/REST API transport
+        DATABASE: Database connection transport (PostgreSQL, etc.)
+        KAFKA: Kafka message broker transport
+        CONSUL: Consul discovery transport
+        VAULT: HashiCorp Vault secret transport
+        VALKEY: Valkey (Redis-compatible) cache/message transport
+        GRPC: gRPC protocol transport
+        RUNTIME: Runtime host process internal transport
+        MCP: Model Context Protocol transport for AI agent integration
+        FILESYSTEM: Local filesystem transport
+        INMEMORY: In-memory transport for testing and local development
+        QDRANT: Qdrant vector database transport
+        GRAPH: Graph database (Memgraph/Neo4j) transport
+    """
+
+    HTTP = "http"
+    DATABASE = "db"
+    KAFKA = "kafka"
+    CONSUL = "consul"
+    VAULT = "vault"
+    VALKEY = "valkey"
+    GRPC = "grpc"
+    RUNTIME = "runtime"
+    MCP = "mcp"
+    FILESYSTEM = "filesystem"
+    INMEMORY = "inmemory"
+    QDRANT = "qdrant"
+    GRAPH = "graph"
+
+
+__all__ = ["EnumInfraTransportType"]

omnibase_infra/enums/enum_introspection_reason.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Introspection Reason Enumeration.
+
+Defines reason values for node introspection events, categorizing why a node
+emits an introspection event for filtering, alerting, and analytics.
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class EnumIntrospectionReason(str, Enum):
+    """
+    Reasons why a node emits an introspection event.
+
+    Used by ModelNodeIntrospectionEvent to categorize introspection
+    events for filtering, alerting, and analytics.
+
+    Values:
+        STARTUP: Node just started and is announcing presence.
+        SHUTDOWN: Node is gracefully shutting down.
+        REQUEST: Explicit request for introspection (e.g., admin query).
+        HEARTBEAT: Periodic health heartbeat.
+        HEALTH_CHANGE: Node health status changed.
+        CAPABILITY_CHANGE: Node capabilities changed at runtime.
+
+    Example:
+        >>> reason = EnumIntrospectionReason.STARTUP
+        >>> reason.is_lifecycle_event()
+        True
+        >>> str(EnumIntrospectionReason.HEARTBEAT)
+        'heartbeat'
+    """
+
+    STARTUP = "startup"
+    """Node just started and is announcing presence."""
+
+    SHUTDOWN = "shutdown"
+    """Node is gracefully shutting down."""
+
+    REQUEST = "request"
+    """Explicit request for introspection (e.g., admin query)."""
+
+    HEARTBEAT = "heartbeat"
+    """Periodic health heartbeat."""
+
+    HEALTH_CHANGE = "health_change"
+    """Node health status changed."""
+
+    CAPABILITY_CHANGE = "capability_change"
+    """Node capabilities changed at runtime."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    def is_lifecycle_event(self) -> bool:
+        """
+        Check if this reason represents a lifecycle event.
+
+        Lifecycle events indicate node startup or shutdown, which are
+        significant for registration and discovery workflows.
+
+        Returns:
+            True if the reason is a lifecycle event, False otherwise
+
+        Example:
+            >>> EnumIntrospectionReason.STARTUP.is_lifecycle_event()
+            True
+            >>> EnumIntrospectionReason.HEARTBEAT.is_lifecycle_event()
+            False
+        """
+        return self in {
+            EnumIntrospectionReason.STARTUP,
+            EnumIntrospectionReason.SHUTDOWN,
+        }
+
+    def is_health_related(self) -> bool:
+        """
+        Check if this reason is health-related.
+
+        Health-related reasons indicate the node is reporting its health
+        status, either periodically or due to a change.
+
+        Returns:
+            True if the reason is health-related, False otherwise
+
+        Example:
+            >>> EnumIntrospectionReason.HEARTBEAT.is_health_related()
+            True
+            >>> EnumIntrospectionReason.REQUEST.is_health_related()
+            False
+        """
+        return self in {
+            EnumIntrospectionReason.HEARTBEAT,
+            EnumIntrospectionReason.HEALTH_CHANGE,
+        }
+
+    def is_change_event(self) -> bool:
+        """
+        Check if this reason indicates a state change.
+
+        Change events indicate something about the node changed that
+        may require re-evaluation by the registration system.
+
+        Returns:
+            True if the reason indicates a change, False otherwise
+
+        Example:
+            >>> EnumIntrospectionReason.CAPABILITY_CHANGE.is_change_event()
+            True
+            >>> EnumIntrospectionReason.HEARTBEAT.is_change_event()
+            False
+        """
+        return self in {
+            EnumIntrospectionReason.HEALTH_CHANGE,
+            EnumIntrospectionReason.CAPABILITY_CHANGE,
+        }
+
+    @classmethod
+    def get_description(cls, reason: "EnumIntrospectionReason") -> str:
+        """
+        Get a human-readable description of the introspection reason.
+
+        Args:
+            reason: The introspection reason to describe
+
+        Returns:
+            A human-readable description of the reason
+
+        Example:
+            >>> EnumIntrospectionReason.get_description(
+            ...     EnumIntrospectionReason.STARTUP
+            ... )
+            'Node just started and is announcing presence'
+        """
+        descriptions = {
+            cls.STARTUP: "Node just started and is announcing presence",
+            cls.SHUTDOWN: "Node is gracefully shutting down",
+            cls.REQUEST: "Explicit request for introspection",
+            cls.HEARTBEAT: "Periodic health heartbeat",
+            cls.HEALTH_CHANGE: "Node health status changed",
+            cls.CAPABILITY_CHANGE: "Node capabilities changed at runtime",
+        }
+        return descriptions.get(reason, "Unknown introspection reason")
+
+
+__all__: list[str] = ["EnumIntrospectionReason"]

omnibase_infra/enums/enum_message_category.py

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Message Category Enumeration.
+
+Defines the fundamental message categories in ONEX event-driven architecture:
+- EVENT: Domain events representing facts that have occurred
+- COMMAND: Instructions to perform an action
+- INTENT: User intents requiring interpretation and routing
+
+IMPORTANT: PROJECTION is NOT a message category. Projections are node output types
+used for execution shape validation (see EnumNodeOutputType). Projections are
+state outputs produced by REDUCER nodes and are not routed via Kafka topics.
+
+Topic Naming Conventions:
+    - EVENT: Read from `*.events` topics (e.g., `order.events`, `user.events`)
+    - COMMAND: Read from `*.commands` topics (e.g., `order.commands`)
+    - INTENT: Read from `*.intents` topics (e.g., `checkout.intents`)
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+
+See Also:
+    EnumNodeOutputType: For node output types including PROJECTION
+"""
+
+from __future__ import annotations
+
+from enum import Enum, unique
+
+
+@unique
+class EnumMessageCategory(str, Enum):
+    """
+    Message category classification for ONEX event-driven routing.
+
+    The three fundamental message categories determine how messages are
+    processed and routed through the system:
+
+    - **EVENT**: Facts that have occurred (past tense, immutable)
+      - Published to event topics (*.events.*)
+      - Consumed by reducers and projections
+      - Example: UserCreatedEvent, OrderCompletedEvent
+
+    - **COMMAND**: Instructions to perform an action (imperative)
+      - Published to command topics (*.commands.*)
+      - Consumed by command handlers
+      - Example: CreateUserCommand, ProcessPaymentCommand
+
+    - **INTENT**: User intents requiring interpretation (declarative)
+      - Published to intent topics (*.intents.*)
+      - Consumed by orchestrators for routing decisions
+      - Example: UserWantsToCheckoutIntent, RequestPasswordResetIntent
+
+    Note:
+        PROJECTION is intentionally NOT included here. Projections are
+        node output types (see EnumNodeOutputType), not routable message
+        categories. REDUCERs produce projections as state outputs.
+
+    Maintainer Note:
+        When adding new values to this enum, you MUST update the following:
+
+        1. ``_MESSAGE_CATEGORY_TO_OUTPUT_TYPE`` mapping in
+           ``omnibase_infra/validation/execution_shape_validator.py``
+        2. ``_CATEGORY_TO_SUFFIX`` and ``_SUFFIX_TO_CATEGORY`` mappings
+           at the bottom of this file (see module-level constants)
+        3. Topic routing logic in ``topic_category_validator.py`` and
+           any pattern matching that uses category suffixes
+        4. The ``from_topic()`` method if the new category uses a
+           different topic naming convention
+
+    Attributes:
+        topic_suffix: The plural suffix used in topic names (e.g., "events")
+
+    Example:
+        >>> category = EnumMessageCategory.EVENT
+        >>> category.topic_suffix
+        'events'
+        >>> EnumMessageCategory.from_topic("onex.user.events")
+        <EnumMessageCategory.EVENT: 'event'>
+        >>> EnumMessageCategory.from_topic("dev.order.commands.v1")
+        <EnumMessageCategory.COMMAND: 'command'>
+    """
+
+    EVENT = "event"
+    """Domain events representing facts that have occurred."""
+
+    COMMAND = "command"
+    """Instructions to perform an action."""
+
+    INTENT = "intent"
+    """User intents requiring interpretation and routing."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    @property
+    def topic_suffix(self) -> str:
+        """
+        Get the topic suffix for this category (plural form).
+
+        The suffix is used in topic naming conventions:
+        - EVENT -> "events" (e.g., onex.user.events)
+        - COMMAND -> "commands" (e.g., onex.order.commands)
+        - INTENT -> "intents" (e.g., onex.checkout.intents)
+
+        Returns:
+            The plural suffix string for topic names
+
+        Example:
+            >>> EnumMessageCategory.EVENT.topic_suffix
+            'events'
+            >>> EnumMessageCategory.COMMAND.topic_suffix
+            'commands'
+        """
+        return _CATEGORY_TO_SUFFIX[self]
+
+    @classmethod
+    def from_topic(cls, topic: str) -> EnumMessageCategory | None:
+        """
+        Infer the message category from a topic string.
+
+        Examines the topic for category keywords (events, commands, intents)
+        as complete segments and returns the corresponding category. Handles both
+        ONEX Kafka format (onex.<domain>.<type>) and Environment-Aware format
+        (<env>.<domain>.<category>.<version>).
+
+        The matching is segment-based to prevent false positives. For example:
+        - "onex.user.events" matches EVENT (segment "events" exists)
+        - "dev.eventsource.data.v1" does NOT match ("eventsource" != "events")
+
+        Args:
+            topic: The topic string to analyze
+
+        Returns:
+            EnumMessageCategory if a category can be inferred, None otherwise
+
+        Example:
+            >>> EnumMessageCategory.from_topic("onex.user.events")
+            <EnumMessageCategory.EVENT: 'event'>
+            >>> EnumMessageCategory.from_topic("dev.order.commands.v1")
+            <EnumMessageCategory.COMMAND: 'command'>
+            >>> EnumMessageCategory.from_topic("prod.checkout.intents.v2")
+            <EnumMessageCategory.INTENT: 'intent'>
+            >>> EnumMessageCategory.from_topic("invalid.topic")
+            None
+            >>> EnumMessageCategory.from_topic("dev.eventsource.data.v1")
+            None  # No false positive: "eventsource" is not the same as "events"
+        """
+        if not topic:
+            return None
+
+        # Split topic into segments and check for exact category suffix matches.
+        # This prevents false positives where a segment merely contains the
+        # category suffix as a substring (e.g., "eventsource" containing "events").
+        segments = topic.lower().split(".")
+        for suffix, category in _SUFFIX_TO_CATEGORY.items():
+            if suffix in segments:
+                return category
+
+        return None
+
+    @classmethod
+    def from_suffix(cls, suffix: str) -> EnumMessageCategory | None:
+        """
+        Get the category from a topic suffix.
+
+        Args:
+            suffix: The suffix to look up (e.g., "events", "commands", "intents")
+
+        Returns:
+            EnumMessageCategory if the suffix is valid, None otherwise
+
+        Example:
+            >>> EnumMessageCategory.from_suffix("events")
+            <EnumMessageCategory.EVENT: 'event'>
+            >>> EnumMessageCategory.from_suffix("commands")
+            <EnumMessageCategory.COMMAND: 'command'>
+            >>> EnumMessageCategory.from_suffix("unknown")
+            None
+        """
+        return _SUFFIX_TO_CATEGORY.get(suffix.lower())
+
+    def is_event(self) -> bool:
+        """Check if this is an event category."""
+        return self == EnumMessageCategory.EVENT
+
+    def is_command(self) -> bool:
+        """Check if this is a command category."""
+        return self == EnumMessageCategory.COMMAND
+
+    def is_intent(self) -> bool:
+        """Check if this is an intent category."""
+        return self == EnumMessageCategory.INTENT
+
+
+# Module-level constant mappings for better performance (avoid dict creation per call)
+# Defined after enum class to enable proper type resolution
+_CATEGORY_TO_SUFFIX: dict[EnumMessageCategory, str] = {
+    EnumMessageCategory.EVENT: "events",
+    EnumMessageCategory.COMMAND: "commands",
+    EnumMessageCategory.INTENT: "intents",
+}
+_SUFFIX_TO_CATEGORY: dict[str, EnumMessageCategory] = {
+    "events": EnumMessageCategory.EVENT,
+    "commands": EnumMessageCategory.COMMAND,
+    "intents": EnumMessageCategory.INTENT,
+}
+
+
+__all__ = ["EnumMessageCategory"]