omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/enums/enum_registration_state.py

@@ -0,0 +1,261 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Registration State Enumeration.
+
+Defines FSM state values for the ONEX two-way node registration workflow.
+Used to track the registration lifecycle from initial introspection through
+active operation and eventual expiry.
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+
+Related Tickets:
+    - OMN-944 (F1): Implement Registration Projection Schema
+    - OMN-888 (C1): Registration Orchestrator
+    - OMN-889 (D1): Registration Reducer
+"""
+
+from enum import StrEnum, unique
+
+
+@unique
+class EnumRegistrationState(StrEnum):
+    """
+    FSM state values for the node registration workflow.
+
+    Represents the operational state of a node's registration at any moment.
+    The registration transitions through these states during its lifecycle:
+
+    Typical Flow:
+        PENDING_REGISTRATION -> ACCEPTED -> AWAITING_ACK -> ACK_RECEIVED -> ACTIVE
+        ACTIVE -> LIVENESS_EXPIRED (terminal)
+
+    Alternative Flows:
+        PENDING_REGISTRATION -> REJECTED (terminal)
+        AWAITING_ACK -> ACK_TIMED_OUT -> PENDING_REGISTRATION (retry)
+
+    Values:
+        PENDING_REGISTRATION: Initial state after NodeRegistrationInitiated
+        ACCEPTED: Registration accepted by orchestrator
+        AWAITING_ACK: Waiting for node to acknowledge registration
+        REJECTED: Registration rejected by orchestrator (terminal)
+        ACK_TIMED_OUT: Ack deadline passed (retriable)
+        ACK_RECEIVED: Node acknowledged registration
+        ACTIVE: Node is fully active and healthy
+        LIVENESS_EXPIRED: Liveness check failed (terminal)
+
+    Example:
+        >>> state = EnumRegistrationState.ACTIVE
+        >>> state.is_active()
+        True
+        >>> EnumRegistrationState.REJECTED.is_terminal()
+        True
+        >>> str(EnumRegistrationState.PENDING_REGISTRATION)
+        'pending_registration'
+    """
+
+    PENDING_REGISTRATION = "pending_registration"
+    """Initial state after NodeRegistrationInitiated event."""
+
+    ACCEPTED = "accepted"
+    """Registration accepted by orchestrator, awaiting node acknowledgment."""
+
+    AWAITING_ACK = "awaiting_ack"
+    """Waiting for node to acknowledge its registration."""
+
+    REJECTED = "rejected"
+    """Registration rejected by orchestrator (terminal state)."""
+
+    ACK_TIMED_OUT = "ack_timed_out"
+    """Acknowledgment deadline passed without response (retriable)."""
+
+    ACK_RECEIVED = "ack_received"
+    """Node acknowledged its registration, transitioning to active."""
+
+    ACTIVE = "active"
+    """Node is fully active and healthy."""
+
+    LIVENESS_EXPIRED = "liveness_expired"
+    """Liveness check failed - node is considered dead (terminal)."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    def is_terminal(self) -> bool:
+        """
+        Check if this is a terminal state (no further transitions expected).
+
+        Terminal states represent registration endpoints where the workflow
+        cannot continue without external intervention (re-registration).
+
+        Returns:
+            True if the state is terminal, False otherwise
+
+        Example:
+            >>> EnumRegistrationState.REJECTED.is_terminal()
+            True
+            >>> EnumRegistrationState.ACTIVE.is_terminal()
+            False
+        """
+        return self in {
+            EnumRegistrationState.REJECTED,
+            EnumRegistrationState.LIVENESS_EXPIRED,
+        }
+
+    def is_active(self) -> bool:
+        """
+        Check if node is considered operationally active.
+
+        Active state means the node is fully registered and healthy,
+        ready to receive work assignments.
+
+        Returns:
+            True if the node is active, False otherwise
+
+        Example:
+            >>> EnumRegistrationState.ACTIVE.is_active()
+            True
+            >>> EnumRegistrationState.AWAITING_ACK.is_active()
+            False
+        """
+        return self == EnumRegistrationState.ACTIVE
+
+    def requires_ack(self) -> bool:
+        """
+        Check if state is waiting for node acknowledgment.
+
+        These states have an ack_deadline that must be monitored
+        for timeout handling (per C2 durable timeout).
+
+        Returns:
+            True if waiting for ack, False otherwise
+
+        Example:
+            >>> EnumRegistrationState.AWAITING_ACK.requires_ack()
+            True
+            >>> EnumRegistrationState.ACTIVE.requires_ack()
+            False
+        """
+        return self in {
+            EnumRegistrationState.ACCEPTED,
+            EnumRegistrationState.AWAITING_ACK,
+        }
+
+    def requires_liveness(self) -> bool:
+        """
+        Check if state requires liveness monitoring.
+
+        Active nodes must maintain liveness through heartbeats.
+        The liveness_deadline must be monitored for expiry.
+
+        Returns:
+            True if liveness monitoring required, False otherwise
+
+        Example:
+            >>> EnumRegistrationState.ACTIVE.requires_liveness()
+            True
+            >>> EnumRegistrationState.PENDING_REGISTRATION.requires_liveness()
+            False
+        """
+        return self == EnumRegistrationState.ACTIVE
+
+    def can_retry(self) -> bool:
+        """
+        Check if this state allows retry of registration.
+
+        Some non-terminal states allow the registration process
+        to be retried by transitioning back to PENDING_REGISTRATION.
+
+        Returns:
+            True if retry is allowed, False otherwise
+
+        Example:
+            >>> EnumRegistrationState.ACK_TIMED_OUT.can_retry()
+            True
+            >>> EnumRegistrationState.REJECTED.can_retry()
+            False
+        """
+        return self == EnumRegistrationState.ACK_TIMED_OUT
+
+    def can_transition_to(self, target: "EnumRegistrationState") -> bool:
+        """
+        Check if transition to target state is valid per FSM contract.
+
+        Validates that the requested state transition follows the
+        defined workflow rules.
+
+        Args:
+            target: The target state to transition to
+
+        Returns:
+            True if the transition is valid, False otherwise
+
+        Example:
+            >>> EnumRegistrationState.PENDING_REGISTRATION.can_transition_to(
+            ...     EnumRegistrationState.ACCEPTED
+            ... )
+            True
+            >>> EnumRegistrationState.ACTIVE.can_transition_to(
+            ...     EnumRegistrationState.PENDING_REGISTRATION
+            ... )
+            False
+        """
+        valid_transitions: dict[EnumRegistrationState, set[EnumRegistrationState]] = {
+            EnumRegistrationState.PENDING_REGISTRATION: {
+                EnumRegistrationState.ACCEPTED,
+                EnumRegistrationState.REJECTED,
+            },
+            EnumRegistrationState.ACCEPTED: {
+                EnumRegistrationState.AWAITING_ACK,
+            },
+            EnumRegistrationState.AWAITING_ACK: {
+                EnumRegistrationState.ACK_RECEIVED,
+                EnumRegistrationState.ACK_TIMED_OUT,
+            },
+            EnumRegistrationState.ACK_RECEIVED: {
+                EnumRegistrationState.ACTIVE,
+            },
+            EnumRegistrationState.ACTIVE: {
+                EnumRegistrationState.LIVENESS_EXPIRED,
+            },
+            EnumRegistrationState.ACK_TIMED_OUT: {
+                EnumRegistrationState.PENDING_REGISTRATION,  # Retry
+            },
+            # Terminal states have no valid transitions
+            EnumRegistrationState.REJECTED: set(),
+            EnumRegistrationState.LIVENESS_EXPIRED: set(),
+        }
+        return target in valid_transitions.get(self, set())
+
+    @classmethod
+    def get_description(cls, state: "EnumRegistrationState") -> str:
+        """
+        Get a human-readable description of the registration state.
+
+        Args:
+            state: The registration state to describe
+
+        Returns:
+            A human-readable description of the state
+
+        Example:
+            >>> EnumRegistrationState.get_description(EnumRegistrationState.ACTIVE)
+            'Node is fully active and healthy'
+        """
+        descriptions = {
+            cls.PENDING_REGISTRATION: "Initial state after registration initiated",
+            cls.ACCEPTED: "Registration accepted, awaiting node acknowledgment",
+            cls.AWAITING_ACK: "Waiting for node to acknowledge registration",
+            cls.REJECTED: "Registration rejected by orchestrator",
+            cls.ACK_TIMED_OUT: "Acknowledgment deadline passed without response",
+            cls.ACK_RECEIVED: "Node acknowledged registration",
+            cls.ACTIVE: "Node is fully active and healthy",
+            cls.LIVENESS_EXPIRED: "Liveness check failed - node is considered dead",
+        }
+        return descriptions.get(state, "Unknown registration state")
+
+
+__all__: list[str] = ["EnumRegistrationState"]

omnibase_infra/enums/enum_registration_status.py

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registration status enumeration.
+
+This module defines the status enumeration for registration operations,
+tracking the overall progress of multi-backend registration workflows.
+"""
+
+from enum import Enum
+
+
+class EnumRegistrationStatus(str, Enum):
+    """Registration workflow status.
+
+    Tracks the overall status of a registration operation that may involve
+    multiple backends (e.g., Consul and PostgreSQL).
+
+    Attributes:
+        IDLE: Registration not started
+        PENDING: Registration in progress, awaiting backend confirmations
+        PARTIAL: Some backends confirmed, others pending or failed
+        COMPLETE: All backends confirmed successfully
+        FAILED: Registration failed across all backends
+    """
+
+    IDLE = "idle"
+    PENDING = "pending"
+    PARTIAL = "partial"
+    COMPLETE = "complete"
+    FAILED = "failed"
+
+
+__all__: list[str] = ["EnumRegistrationStatus"]

omnibase_infra/enums/enum_registry_response_status.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Registry response status enumeration.
+
+This module defines the status enumeration for registry operation responses,
+indicating the outcome of registry queries and mutations.
+"""
+
+from enum import Enum
+
+
+class EnumRegistryResponseStatus(str, Enum):
+    """Registry operation response status.
+
+    Indicates the outcome of a registry operation.
+
+    Attributes:
+        SUCCESS: Registry operation completed successfully
+        PARTIAL: Operation partially succeeded (some items processed)
+        FAILED: Registry operation failed
+    """
+
+    SUCCESS = "success"
+    PARTIAL = "partial"
+    FAILED = "failed"
+
+
+__all__: list[str] = ["EnumRegistryResponseStatus"]

omnibase_infra/enums/enum_response_status.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler response status enumeration.
+
+This module defines the status enumeration for handler responses,
+indicating whether the handler operation completed successfully or with an error.
+"""
+
+from enum import Enum
+
+
+class EnumResponseStatus(str, Enum):
+    """Handler response status for operation results.
+
+    Indicates the outcome of a handler operation.
+
+    Attributes:
+        SUCCESS: Handler operation completed successfully
+        ERROR: Handler operation failed with an error
+    """
+
+    SUCCESS = "success"
+    ERROR = "error"
+
+
+__all__: list[str] = ["EnumResponseStatus"]

omnibase_infra/enums/enum_retry_error_category.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Retry Error Category Enumeration.
+
+Defines classification categories for errors during retry handling in
+infrastructure handlers. Used to determine retry eligibility and circuit
+breaker behavior.
+
+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 EnumRetryErrorCategory(str, Enum):
+    """Classification of errors for retry decision making.
+
+    Error categories determine:
+    - Whether to retry the operation
+    - Whether to record circuit breaker failure
+    - Which error type to raise after retries exhausted
+
+    Values:
+        TIMEOUT: Operation timed out - retry eligible, circuit breaker failure on exhaustion.
+        AUTHENTICATION: Authentication/permission error - no retry, immediate circuit breaker failure.
+        CONNECTION: Connection/network error - retry eligible, circuit breaker failure on exhaustion.
+        NOT_FOUND: Resource not found - no retry, no circuit breaker failure (user error).
+        UNKNOWN: Unknown/unexpected error - retry eligible, circuit breaker failure on exhaustion.
+
+    Example:
+        >>> category = EnumRetryErrorCategory.TIMEOUT
+        >>> category.is_retry_eligible()
+        True
+        >>> EnumRetryErrorCategory.AUTHENTICATION.is_retry_eligible()
+        False
+    """
+
+    TIMEOUT = "timeout"
+    """Operation timed out - retry eligible, circuit breaker failure on exhaustion."""
+
+    AUTHENTICATION = "authentication"
+    """Authentication/permission error - no retry, immediate circuit breaker failure."""
+
+    CONNECTION = "connection"
+    """Connection/network error - retry eligible, circuit breaker failure on exhaustion."""
+
+    NOT_FOUND = "not_found"
+    """Resource not found - no retry, no circuit breaker failure (user error)."""
+
+    UNKNOWN = "unknown"
+    """Unknown/unexpected error - retry eligible, circuit breaker failure on exhaustion."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    def is_retry_eligible(self) -> bool:
+        """Check if this error category is eligible for retry.
+
+        Returns:
+            True if the error category allows retry, False otherwise.
+
+        Example:
+            >>> EnumRetryErrorCategory.CONNECTION.is_retry_eligible()
+            True
+            >>> EnumRetryErrorCategory.NOT_FOUND.is_retry_eligible()
+            False
+        """
+        return self in {
+            EnumRetryErrorCategory.TIMEOUT,
+            EnumRetryErrorCategory.CONNECTION,
+            EnumRetryErrorCategory.UNKNOWN,
+        }
+
+    def records_circuit_failure(self) -> bool:
+        """Check if this error category should record circuit breaker failure.
+
+        Returns:
+            True if the error should be recorded as a circuit breaker failure.
+
+        Example:
+            >>> EnumRetryErrorCategory.AUTHENTICATION.records_circuit_failure()
+            True
+            >>> EnumRetryErrorCategory.NOT_FOUND.records_circuit_failure()
+            False
+        """
+        return self in {
+            EnumRetryErrorCategory.TIMEOUT,
+            EnumRetryErrorCategory.AUTHENTICATION,
+            EnumRetryErrorCategory.CONNECTION,
+            EnumRetryErrorCategory.UNKNOWN,
+        }
+
+
+__all__: list[str] = ["EnumRetryErrorCategory"]

omnibase_infra/enums/enum_security_rule_id.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Security validation rule IDs for OMN-1098.
+
+This module defines the security rule identifiers used in validation errors
+for handler security policy enforcement. These IDs provide structured error
+codes for both registration-time and invocation-time security violations.
+
+Rule ID Structure:
+    - SECURITY-3xx: Security-related violations
+    - 300-309: Registration-time violations (policy declaration errors)
+    - 310-319: Invocation-time violations (runtime enforcement errors)
+
+Usage:
+    These rule IDs are used in validation error models to provide
+    machine-readable error codes for security violations.
+
+See Also:
+    - ModelHandlerSecurityPolicy: Handler-declared security requirements
+    - ModelEnvironmentPolicy: Environment-level security constraints
+"""
+
+from enum import StrEnum
+
+
+class EnumSecurityRuleId(StrEnum):
+    """Security rule identifiers for validation errors.
+
+    Provides structured error codes for handler security policy violations.
+    Used to categorize and identify specific security constraint failures
+    during handler registration and invocation.
+
+    Two-Layer Security Validation Architecture:
+        The security system validates handlers at two distinct points:
+
+        1. Registration-Time Violations (300-309):
+            Validated by: RegistrationSecurityValidator
+            Location: omnibase_infra.validation.registration_security_validator
+            When: Handler attempts to register with the system
+            Purpose: Prevents misconfigured handlers from registering
+
+        2. Invocation-Time Violations (310-319):
+            Enforced by: InvocationSecurityEnforcer
+            Location: omnibase_infra.runtime.invocation_security_enforcer
+            When: Handler attempts to access resources at runtime
+            Purpose: Enforces declared policy during handler execution
+
+    Attributes:
+        SECRET_SCOPE_NOT_PERMITTED: Handler requests secret scope not permitted
+            in the current environment. (Registration-time, SECURITY-300)
+        CLASSIFICATION_EXCEEDS_MAX: Handler's data classification exceeds the
+            maximum allowed for the environment. (Registration-time, SECURITY-301)
+        ADAPTER_REQUESTING_SECRETS: Adapter handler attempting to request secrets
+            (adapters should not access secrets directly). (Registration-time, SECURITY-302)
+        ADAPTER_NON_EFFECT_CATEGORY: Adapter handler has non-EFFECT category
+            (adapters must be EFFECT handlers). (Registration-time, SECURITY-303)
+        ADAPTER_MISSING_DOMAIN_ALLOWLIST: Adapter handler missing required
+            domain allowlist in environment requiring explicit allowlists.
+            (Registration-time, SECURITY-304)
+        EFFECT_MISSING_SECURITY_METADATA: EFFECT handler missing required
+            security metadata (must have secret_scopes, allowed_domains, or
+            data_classification). (Handler-type validation, SECURITY-305)
+        COMPUTE_HAS_SECURITY_METADATA: COMPUTE handler has security metadata
+            (COMPUTE handlers must not have security metadata).
+            (Handler-type validation, SECURITY-306)
+        INVALID_SECRET_SCOPE: Secret scope is invalid (empty or whitespace-only).
+            (Handler-type validation, SECURITY-307)
+        INVALID_DOMAIN_PATTERN: Domain pattern in allowlist is invalid.
+            (Handler-type validation, SECURITY-308)
+        DOMAIN_ACCESS_DENIED: Handler attempted to access domain not in its
+            declared allowlist. (Invocation-time, SECURITY-310)
+        SECRET_SCOPE_ACCESS_DENIED: Handler attempted to access secret scope
+            not in its declared scopes. (Invocation-time, SECURITY-311)
+        CLASSIFICATION_CONSTRAINT_VIOLATION: Data processed exceeds handler's
+            declared classification level. (Invocation-time, SECURITY-312)
+
+    See Also:
+        - RegistrationSecurityValidator: Registration-time validation
+        - InvocationSecurityEnforcer: Invocation-time enforcement
+        - ModelHandlerSecurityPolicy: Handler-declared security requirements
+        - ModelEnvironmentPolicy: Environment-level security constraints
+    """
+
+    # Registration-time violations (300-309)
+    SECRET_SCOPE_NOT_PERMITTED = "SECURITY-300"
+    CLASSIFICATION_EXCEEDS_MAX = "SECURITY-301"
+    ADAPTER_REQUESTING_SECRETS = "SECURITY-302"
+    ADAPTER_NON_EFFECT_CATEGORY = "SECURITY-303"
+    ADAPTER_MISSING_DOMAIN_ALLOWLIST = "SECURITY-304"
+
+    # Handler type security violations (305-309) - OMN-1137
+    EFFECT_MISSING_SECURITY_METADATA = "SECURITY-305"
+    COMPUTE_HAS_SECURITY_METADATA = "SECURITY-306"
+    INVALID_SECRET_SCOPE = "SECURITY-307"
+    INVALID_DOMAIN_PATTERN = "SECURITY-308"
+
+    # Invocation-time violations (310-319)
+    DOMAIN_ACCESS_DENIED = "SECURITY-310"
+    SECRET_SCOPE_ACCESS_DENIED = "SECURITY-311"
+    CLASSIFICATION_CONSTRAINT_VIOLATION = "SECURITY-312"
+
+
+__all__ = ["EnumSecurityRuleId"]

omnibase_infra/enums/enum_selection_strategy.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Selection Strategy Enumeration.
+
+Defines strategies for selecting a node from multiple candidates that match
+capability-based discovery criteria.
+
+Related Tickets:
+    - OMN-1135: ServiceCapabilityQuery for capability-based discovery
+
+Example:
+    >>> from omnibase_infra.enums import EnumSelectionStrategy
+    >>> strategy = EnumSelectionStrategy.ROUND_ROBIN
+    >>> print(strategy.value)
+    'round_robin'
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class EnumSelectionStrategy(str, Enum):
+    """Selection strategies for choosing among multiple capability matches.
+
+    When capability-based discovery finds multiple nodes that match the
+    requested criteria, this strategy determines which node is selected.
+
+    Values:
+        FIRST: Return the first candidate (deterministic, fast).
+            Best for: Development, testing, or when order matters.
+        RANDOM: Randomly select from candidates.
+            Best for: Simple load distribution without state.
+        ROUND_ROBIN: Cycle through candidates sequentially.
+            Best for: Even distribution with state tracking.
+        LEAST_LOADED: Select based on current load metrics.
+            Best for: Production load balancing (requires metrics).
+
+    Example:
+        >>> strategy = EnumSelectionStrategy.FIRST
+        >>> strategy.value
+        'first'
+        >>> str(EnumSelectionStrategy.ROUND_ROBIN)
+        'round_robin'
+    """
+
+    FIRST = "first"
+    """Return the first candidate (deterministic, fast)."""
+
+    RANDOM = "random"
+    """Randomly select from candidates."""
+
+    ROUND_ROBIN = "round_robin"
+    """Cycle through candidates sequentially."""
+
+    LEAST_LOADED = "least_loaded"
+    """Select based on current load metrics (future implementation)."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    def requires_state(self) -> bool:
+        """Check if this strategy requires state tracking.
+
+        Returns:
+            True if the strategy needs persistent state (e.g., round-robin index).
+
+        Example:
+            >>> EnumSelectionStrategy.ROUND_ROBIN.requires_state()
+            True
+            >>> EnumSelectionStrategy.FIRST.requires_state()
+            False
+        """
+        return self in {EnumSelectionStrategy.ROUND_ROBIN}
+
+    def requires_metrics(self) -> bool:
+        """Check if this strategy requires load metrics.
+
+        Returns:
+            True if the strategy needs external metrics (e.g., least-loaded).
+
+        Example:
+            >>> EnumSelectionStrategy.LEAST_LOADED.requires_metrics()
+            True
+            >>> EnumSelectionStrategy.RANDOM.requires_metrics()
+            False
+        """
+        return self == EnumSelectionStrategy.LEAST_LOADED
+
+
+__all__: list[str] = ["EnumSelectionStrategy"]

omnibase_infra/enums/enum_topic_standard.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Topic Standard Enumeration.
+
+Defines the recognized topic naming standards for ONEX message routing.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class EnumTopicStandard(str, Enum):
+    """
+    Enumeration of recognized topic naming standards.
+
+    ONEX supports multiple topic naming conventions depending on the context
+    and deployment environment:
+
+    - ONEX_KAFKA: The canonical ONEX Kafka format: onex.<domain>.<type>
+    - ENVIRONMENT_AWARE: Environment-prefixed format: <env>.<domain>.<category>.<version>
+    - UNKNOWN: Topic format could not be determined
+
+    Example:
+        >>> EnumTopicStandard.ONEX_KAFKA.value
+        'onex_kafka'
+        >>> str(EnumTopicStandard.ENVIRONMENT_AWARE)
+        'environment_aware'
+    """
+
+    ONEX_KAFKA = "onex_kafka"
+    """ONEX Kafka standard: onex.<domain>.<type>"""
+
+    ENVIRONMENT_AWARE = "environment_aware"
+    """Environment-aware format: <env>.<domain>.<category>.<version>"""
+
+    UNKNOWN = "unknown"
+    """Topic format could not be determined"""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value