feat(validation): add topic suffix validation utilities and contract schema [OMN-1537]

src/omnibase_core/constants/__init__.py

@@ -141,9 +141,13 @@
     TOPIC_RUNTIME_EVENTS,
     TOPIC_RUNTIME_INTENTS,
     TOPIC_TYPE_COMMANDS,
+    TOPIC_TYPE_DLQ,
     TOPIC_TYPE_EVENTS,
     TOPIC_TYPE_INTENTS,
     TOPIC_TYPE_SNAPSHOTS,
+    get_token_to_topic_type,
+    get_topic_type_to_token,
+    get_valid_topic_suffix_kinds,
     topic_name,
 )
 
@@ -250,9 +254,14 @@
     "validate_capabilities",
     # Topic taxonomy constants
     "TOPIC_TYPE_COMMANDS",
+    "TOPIC_TYPE_DLQ",
     "TOPIC_TYPE_EVENTS",
     "TOPIC_TYPE_INTENTS",
     "TOPIC_TYPE_SNAPSHOTS",
+    # Token mapping accessors (OMN-1537)
+    "get_token_to_topic_type",
+    "get_topic_type_to_token",
+    "get_valid_topic_suffix_kinds",
     "DOMAIN_REGISTRATION",
     "DOMAIN_DISCOVERY",
     "DOMAIN_RUNTIME",

src/omnibase_core/constants/constants_topic_taxonomy.py

@@ -11,25 +11,138 @@
 - events: Immutable event logs
 - intents: Coordination intents
 - snapshots: Compacted state snapshots
+- dlq: Dead letter queue (failed messages)
 
 Thread Safety:
     All constants in this module are immutable strings and thread-safe.
     The topic_name() function is pure and thread-safe.
+
+Cross-reference:
+    For topic kind tokens used in suffix validation (TOPIC_KIND_CMD, etc.),
+    see omnibase_core.models.validation.model_topic_suffix_parts.
+    This module defines TOPIC_TYPE_* semantic values (e.g., "commands"),
+    while model_topic_suffix_parts defines TOPIC_KIND_* tokens (e.g., "cmd").
 """
 
+from __future__ import annotations
+
+import functools
 import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.enums.enum_topic_taxonomy import EnumTopicType
 
-# Topic Type Suffixes
+# Topic Type Suffixes (semantic values used internally)
 TOPIC_TYPE_COMMANDS = "commands"
+TOPIC_TYPE_DLQ = "dlq"
 TOPIC_TYPE_EVENTS = "events"
 TOPIC_TYPE_INTENTS = "intents"
 TOPIC_TYPE_SNAPSHOTS = "snapshots"
 
 # Valid topic types set for validation
 _VALID_TOPIC_TYPES = frozenset(
-    {TOPIC_TYPE_COMMANDS, TOPIC_TYPE_EVENTS, TOPIC_TYPE_INTENTS, TOPIC_TYPE_SNAPSHOTS}
+    {
+        TOPIC_TYPE_COMMANDS,
+        TOPIC_TYPE_DLQ,
+        TOPIC_TYPE_EVENTS,
+        TOPIC_TYPE_INTENTS,
+        TOPIC_TYPE_SNAPSHOTS,
+    }
 )
 
+
+# Token-to-Type Mappings
+# Maps short tokens (cmd, evt, dlq, intent, snapshot) used in topic suffixes
+# to their corresponding EnumTopicType semantic values (commands, events, etc.)
+def _build_token_mappings() -> tuple[
+    dict[str, EnumTopicType], dict[EnumTopicType, str], frozenset[str]
+]:
+    """
+    Build token-to-enum and enum-to-token mappings.
+
+    Deferred import to avoid circular dependency at module load time.
+    Called lazily when mappings are first accessed.
+
+    Returns:
+        Tuple of (token_to_type, type_to_token, valid_suffix_kinds).
+    """
+    from omnibase_core.enums.enum_topic_taxonomy import EnumTopicType
+
+    token_to_type: dict[str, EnumTopicType] = {
+        "cmd": EnumTopicType.COMMANDS,
+        "dlq": EnumTopicType.DLQ,
+        "evt": EnumTopicType.EVENTS,
+        "intent": EnumTopicType.INTENTS,
+        "snapshot": EnumTopicType.SNAPSHOTS,
+    }
+    type_to_token: dict[EnumTopicType, str] = {v: k for k, v in token_to_type.items()}
+    valid_kinds: frozenset[str] = frozenset(token_to_type.keys())
+    return token_to_type, type_to_token, valid_kinds
+
+
+@functools.lru_cache(maxsize=1)
+def _get_token_mappings() -> tuple[
+    dict[str, EnumTopicType], dict[EnumTopicType, str], frozenset[str]
+]:
+    """Get or initialize the token mappings (cached via lru_cache)."""
+    return _build_token_mappings()
+
+
+def get_token_to_topic_type() -> dict[str, EnumTopicType]:
+    """
+    Get mapping from topic suffix tokens to EnumTopicType values.
+
+    Topic suffix tokens are the abbreviated forms used in topic names
+    (e.g., 'cmd', 'evt', 'dlq'), while EnumTopicType values are the
+    semantic internal representations (e.g., 'commands', 'events', 'dlq').
+
+    Returns:
+        Dict mapping tokens to enum values.
+
+    Example:
+        >>> mapping = get_token_to_topic_type()
+        >>> mapping["evt"]
+        <EnumTopicType.EVENTS: 'events'>
+    """
+    # Return defensive copy to prevent mutation of cached mapping
+    return dict(_get_token_mappings()[0])
+
+
+def get_topic_type_to_token() -> dict[EnumTopicType, str]:
+    """
+    Get reverse mapping from EnumTopicType values to tokens.
+
+    Used for composing topic suffixes from enum values.
+
+    Returns:
+        Dict mapping enum values to tokens.
+
+    Example:
+        >>> from omnibase_core.enums import EnumTopicType
+        >>> mapping = get_topic_type_to_token()
+        >>> mapping[EnumTopicType.COMMANDS]
+        'cmd'
+    """
+    # Return defensive copy to prevent mutation of cached mapping
+    return dict(_get_token_mappings()[1])
+
+
+def get_valid_topic_suffix_kinds() -> frozenset[str]:
+    """
+    Get the set of valid topic suffix kind tokens.
+
+    Returns:
+        Frozenset of valid tokens ('cmd', 'evt', 'dlq', 'intent', 'snapshot').
+
+    Example:
+        >>> kinds = get_valid_topic_suffix_kinds()
+        >>> "evt" in kinds
+        True
+    """
+    return _get_token_mappings()[2]
+
+
 # Domain validation pattern: lowercase alphanumeric with hyphens, starting with letter,
 # cannot end with hyphen (must end with letter or digit, or be single letter)
 _DOMAIN_PATTERN = re.compile(r"^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$")
@@ -120,9 +233,14 @@ def topic_name(domain: str, topic_type: str) -> str:
 __all__ = [
     # Type suffixes
     "TOPIC_TYPE_COMMANDS",
+    "TOPIC_TYPE_DLQ",
     "TOPIC_TYPE_EVENTS",
     "TOPIC_TYPE_INTENTS",
     "TOPIC_TYPE_SNAPSHOTS",
+    # Token mapping accessors (lazy-loaded to avoid circular imports)
+    "get_token_to_topic_type",
+    "get_topic_type_to_token",
+    "get_valid_topic_suffix_kinds",
     # Domains
     "DOMAIN_REGISTRATION",
     "DOMAIN_DISCOVERY",

src/omnibase_core/enums/enum_topic_taxonomy.py

@@ -19,14 +19,16 @@ class EnumTopicType(StrValueHelper, str, Enum):
     """
     Valid topic types per ONEX topic taxonomy.
 
-    Defines the four standard topic categories used across all ONEX domains:
+    Defines the standard topic categories used across all ONEX domains:
     - COMMANDS: Request/action topics (imperative, exactly-once semantics)
     - EVENTS: Immutable event logs (append-only, time-based retention)
     - INTENTS: Intent coordination topics (workflow orchestration)
     - SNAPSHOTS: State snapshots (compacted, key-based retention)
+    - DLQ: Dead letter queue topics (failed message storage)
     """
 
     COMMANDS = "commands"
+    DLQ = "dlq"
     EVENTS = "events"
     INTENTS = "intents"
     SNAPSHOTS = "snapshots"

src/omnibase_core/models/contracts/subcontracts/__init__.py

@@ -127,6 +127,7 @@
 from .model_statistical_computation import ModelStatisticalComputation
 from .model_synchronization_point import ModelSynchronizationPoint
 from .model_tool_execution_subcontract import ModelToolExecutionSubcontract
+from .model_topic_meta import ModelTopicMeta
 from .model_validation_subcontract import ModelValidationSubcontract
 from .model_validator_rule import ModelValidatorRule
 from .model_validator_subcontract import ModelValidatorSubcontract
@@ -202,6 +203,7 @@
     "ModelEventPersistence",
     "ModelEventRouting",
     "ModelEventTransformation",
+    "ModelTopicMeta",
     # FSM subcontracts and components
     "ModelFSMSubcontract",
     "ModelFSMOperation",

src/omnibase_core/models/contracts/subcontracts/model_event_bus_subcontract.py

@@ -18,12 +18,13 @@
 
 from typing import ClassVar
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from omnibase_core.constants import KAFKA_REQUEST_TIMEOUT_MS
 from omnibase_core.enums.enum_core_error_code import EnumCoreErrorCode
 from omnibase_core.models.common.model_error_context import ModelErrorContext
 from omnibase_core.models.common.model_schema_value import ModelSchemaValue
+from omnibase_core.models.contracts.subcontracts.model_topic_meta import ModelTopicMeta
 from omnibase_core.models.errors.model_onex_error import ModelOnexError
 from omnibase_core.models.primitives.model_semver import ModelSemVer
 
@@ -199,6 +200,41 @@ class ModelEventBusSubcontract(BaseModel):
         description="Default event patterns if no other patterns can be determined",
     )
 
+    # Topic-based routing configuration (OMN-1537)
+    publish_topics: list[str] = Field(
+        default_factory=list,
+        description="Topic suffixes this node publishes to. Format: onex.{kind}.{producer}.{event-name}.v{n}",
+    )
+
+    subscribe_topics: list[str] = Field(
+        default_factory=list,
+        description="Topic suffixes this node subscribes to. Format: onex.{kind}.{producer}.{event-name}.v{n}",
+    )
+
+    # Extension path for future schema_ref support
+    publish_topic_metadata: dict[str, ModelTopicMeta] | None = Field(
+        default=None,
+        description="Optional metadata per publish topic suffix (keyed by suffix string)",
+    )
+
+    subscribe_topic_metadata: dict[str, ModelTopicMeta] | None = Field(
+        default=None,
+        description="Optional metadata per subscribe topic suffix (keyed by suffix string)",
+    )
+
+    @field_validator("publish_topics", "subscribe_topics", mode="after")
+    @classmethod
+    def validate_topic_suffixes(cls, topics: list[str]) -> list[str]:
+        """Validate each topic suffix against ONEX naming convention."""
+        # Import here to avoid circular import at module load time
+        from omnibase_core.validation import validate_topic_suffix
+
+        for topic in topics:
+            result = validate_topic_suffix(topic)
+            if not result.is_valid:
+                raise ValueError(f"Invalid topic suffix '{topic}': {result.error}")
+        return topics
+
     @model_validator(mode="after")
     def validate_event_bus_configuration(self) -> "ModelEventBusSubcontract":
         """Validate event bus configuration fields after model construction."""

src/omnibase_core/models/contracts/subcontracts/model_topic_meta.py

@@ -0,0 +1,37 @@
+"""
+Topic Metadata Model.
+
+Model for topic subscription/publication metadata in ONEX event bus contracts.
+Provides extension point for schema_ref and description per topic.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+__all__ = ["ModelTopicMeta"]
+
+
+class ModelTopicMeta(BaseModel):
+    """
+    Metadata for a topic subscription/publication.
+
+    Provides optional metadata for topics declared in publish_topics
+    and subscribe_topics fields, keyed by the topic suffix string.
+    This is an extension point for future schema validation and
+    documentation generation.
+    """
+
+    schema_ref: str | None = Field(
+        default=None,
+        description="Reference to the Pydantic model for this topic's payload",
+    )
+
+    description: str | None = Field(
+        default=None,
+        description="Human-readable description of this topic's purpose",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )

src/omnibase_core/models/events/model_topic_config.py

@@ -139,6 +139,25 @@ def snapshots_default(cls) -> "ModelTopicConfig":
             replication_factor=1,
         )
 
+    @classmethod
+    def dlq_default(cls) -> "ModelTopicConfig":
+        """
+        Default configuration for dead letter queue (DLQ) topics.
+
+        DLQ topics store failed messages for investigation and retry.
+        Default retention is 30 days per ONEX standard (same as events for audit).
+
+        Note:
+            This model is immutable (frozen) and thread-safe after instantiation.
+        """
+        return cls(
+            topic_type=EnumTopicType.DLQ,
+            cleanup_policy=EnumCleanupPolicy.DELETE,
+            retention_ms=2592000000,  # 30 days per ONEX standard
+            partitions=3,
+            replication_factor=1,
+        )
+
 
 __all__ = [
     "ModelTopicConfig",

src/omnibase_core/models/events/model_topic_manifest.py

@@ -117,6 +117,7 @@ def registration_domain(cls) -> "ModelTopicManifest":
             domain="registration",
             topics={
                 EnumTopicType.COMMANDS: ModelTopicConfig.commands_default(),
+                EnumTopicType.DLQ: ModelTopicConfig.dlq_default(),
                 EnumTopicType.EVENTS: ModelTopicConfig.events_default(),
                 EnumTopicType.INTENTS: ModelTopicConfig.intents_default(),
                 EnumTopicType.SNAPSHOTS: ModelTopicConfig.snapshots_default(),
@@ -128,7 +129,7 @@ def create_standard_manifest(cls, domain: str) -> "ModelTopicManifest":
         """
         Create a standard topic manifest for any domain.
 
-        Creates all four topic types with default configurations.
+        Creates all five topic types with default configurations.
 
         Args:
             domain: Domain name (lowercase, alphanumeric with hyphens)
@@ -140,6 +141,7 @@ def create_standard_manifest(cls, domain: str) -> "ModelTopicManifest":
             domain=domain,
             topics={
                 EnumTopicType.COMMANDS: ModelTopicConfig.commands_default(),
+                EnumTopicType.DLQ: ModelTopicConfig.dlq_default(),
                 EnumTopicType.EVENTS: ModelTopicConfig.events_default(),
                 EnumTopicType.INTENTS: ModelTopicConfig.intents_default(),
                 EnumTopicType.SNAPSHOTS: ModelTopicConfig.snapshots_default(),

src/omnibase_core/models/validation/__init__.py

@@ -27,6 +27,18 @@
 from .model_lint_statistics import ModelLintStatistics
 from .model_migration_conflict_union import ModelMigrationConflictUnion
 from .model_shape_validation_result import ModelShapeValidationResult
+
+# Topic suffix validation models (OMN-1537)
+from .model_topic_suffix_parts import (
+    TOPIC_KIND_CMD,
+    TOPIC_KIND_DLQ,
+    TOPIC_KIND_EVT,
+    TOPIC_KIND_INTENT,
+    TOPIC_KIND_SNAPSHOT,
+    VALID_TOPIC_KINDS,
+    ModelTopicSuffixParts,
+)
+from .model_topic_validation_result import ModelTopicValidationResult
 from .model_unique_name_result import ModelUniqueNameResult
 from .model_validation_base import ModelValidationBase
 from .model_validation_container import ModelValidationContainer
@@ -54,6 +66,15 @@
     "ModelExecutionShape",
     "ModelExecutionShapeValidation",
     "ModelShapeValidationResult",
+    # Topic suffix validation models (OMN-1537)
+    "ModelTopicSuffixParts",
+    "ModelTopicValidationResult",
+    "TOPIC_KIND_CMD",
+    "TOPIC_KIND_DLQ",
+    "TOPIC_KIND_EVT",
+    "TOPIC_KIND_INTENT",
+    "TOPIC_KIND_SNAPSHOT",
+    "VALID_TOPIC_KINDS",
     # Workflow validation models (OMN-176)
     "ModelCycleDetectionResult",
     "ModelDependencyValidationResult",