feat(OMN-1547): Replace hardcoded topics with validated suffix constants

[jonahgabriel]

• Add platform topic suffix constants module with import-time validation
• Add build_full_topic() composition helper with env/namespace/suffix validation
• Update 7 platform files to use suffix constants instead of hardcoded strings
• Remove hardcoded omniclaude domain topics from config_consumer.py
• Consolidate introspection topic definitions (model = canonical, mixin = consumer)
• Add 30 unit tests for suffix validation and topic composition

Summary by CodeRabbit

• New Features

  • Public topic composition utility and a curated set of platform topic suffixes with import-time validation.
  • Session consumer now requires explicit topic configuration and validates topics early.

• Refactor

  • Replaced scattered hard-coded topic strings with centralized platform topic constants and removed legacy public topic names.

• Tests

  • Added comprehensive unit tests for suffixes, composition logic, and validation behaviors.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new omnibase_infra.topics package with platform suffix constants and topic composition utilities, migrates hard-coded topic strings to shared SUFFIX_* constants across configs/services/tests, introduces topic validation/composition and tests, and removes module-level introspection topic constants.

Changes

Cohort / File(s)	Summary
Topics package src/omnibase_infra/topics/platform_topic_suffixes.py, src/omnibase_infra/topics/util_topic_composition.py, src/omnibase_infra/topics/__init__.py	New package: defines SUFFIX_* platform topic suffix constants, ALL_PLATFORM_SUFFIXES, import-time suffix validation, build_full_topic(env, namespace, suffix), TopicCompositionError, MAX_NAMESPACE_LENGTH, and re-exports. Review export names, validation logic, and import-time side effects.
Introspection & discovery src/omnibase_infra/mixins/mixin_node_introspection.py, src/omnibase_infra/models/discovery/model_introspection_config.py	Removed module-level INTROSPECTION_TOPIC, HEARTBEAT_TOPIC, REQUEST_INTROSPECTION_TOPIC; ModelIntrospectionConfig now uses SUFFIX_NODE_* defaults and updated examples. Check callers that imported removed constants.
Runtime & FSM notifications src/omnibase_infra/runtime/models/model_runtime_scheduler_config.py, src/omnibase_infra/runtime/transition_notification_publisher.py	Replaced literal topics with SUFFIX_RUNTIME_TICK and SUFFIX_FSM_STATE_TRANSITIONS. Verify external references expecting previous literal strings.
Services & projections src/omnibase_infra/services/mcp/service_mcp_tool_sync.py, src/omnibase_infra/models/projection/model_snapshot_topic_config.py	Replaced hard-coded registration/snapshot topic strings with SUFFIX_NODE_REGISTRATION and SUFFIX_REGISTRATION_SNAPSHOTS. Confirm consumers/producers and tests updated accordingly.
Session consumer validation src/omnibase_infra/services/session/config_consumer.py	topics field now uses default_factory=list; added validate_topic_configuration() to fail when topics are not explicitly configured; timing validation reordered. Ensure callers/boot config set topics.
Tests & test updates tests/unit/topics/*, tests/unit/mixins/test_mixin_node_introspection.py, tests/unit/models/projection/*, tests/unit/runtime/*, tests/services/session/test_consumer.py	New unit tests for suffixes and composition utilities; updated tests to reference SUFFIX_* constants and to assert fail-fast behavior when topics missing. Run full test suite for coverage.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• chore: bump version to 0.2.4, update omnibase-core to 0.9.5 #194: Adds/exposes topic composition and validation utilities — overlaps with the new topics package and build_full_topic exports.
• feat(projection): implement snapshot publishing for read optimization [OMN-947] #74: Modifies snapshot topic defaults in projection config — related to replacing hard-coded snapshot topic with SUFFIX_REGISTRATION_SNAPSHOTS.
• feat(introspection): Add node introspection with configurable topics [BREAKING] [OMN-881] #54: Changes node introspection topic handling in mixin — related to removal of module-level node.* topic constants.

Poem

🐇 I hopped through code and found new trails,
Suffixes gathered in tidy veils.
I stitched the topics, checked each name,
Env and namespace now play the same game.
A carrot for tests — the build prevails.

🚥 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 accurately describes the main change: replacing hardcoded topic strings with validated suffix constants across the codebase.
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: 4

🤖 Fix all issues with AI agents

In `@src/omnibase_infra/models/discovery/model_introspection_config.py`:
- Around line 31-35: Docstrings for the introspection config fields still
reference legacy "node.*" topics but the defaults now use ONEX suffixes
(SUFFIX_NODE_HEARTBEAT, SUFFIX_NODE_INTROSPECTION,
SUFFIX_REQUEST_INTROSPECTION). Update the module/class/field docstrings in
model_introspection_config.py (including the docstrings that currently describe
the heartbeat/introspection/request topics at the top of the file and the ones
around the fields at the later sections noted) so they reference the new ONEX
topic suffix defaults and show example topic names using the SUFFIX_* constants
(replace or reword any "node.*" examples), and ensure the docstrings for the
fields that use SUFFIX_NODE_HEARTBEAT, SUFFIX_NODE_INTROSPECTION, and
SUFFIX_REQUEST_INTROSPECTION accurately describe their purpose and default
behavior.

In `@src/omnibase_infra/topics/platform_topic_suffixes.py`:
- Around line 125-137: Replace the raised ValueError in _validate_all_suffixes
with an OnexError and chain it from an underlying exception to preserve context:
if validate_topic_suffix(suffix) returns not result.is_valid, construct a small
underlying Exception (e.g. Exception(result.error)) and then raise
OnexError(f"Invalid platform topic suffix '{suffix}': {result.error}") from that
exception; ensure OnexError is imported where _validate_all_suffixes,
validate_topic_suffix, and ALL_PLATFORM_SUFFIXES are referenced.

In `@src/omnibase_infra/topics/util_topic_composition.py`:
- Around line 45-52: Update the namespace validation in
util_topic_composition.py so composed topics follow ONEX lowercase conventions:
either normalize the input by lowercasing (e.g., set namespace =
namespace.lower() before further validation/composition) or explicitly reject
namespaces that contain any uppercase characters by adding a check using
namespace.islower() and raising TopicCompositionError with a clear message;
adjust the existing validation block that currently checks namespace and allowed
chars (variable name namespace and exception TopicCompositionError) accordingly
so downstream topic composition always uses lowercase.
- Around line 11-12: Change TopicCompositionError to inherit from OnexError (or
the appropriate infra base error) instead of ValueError: update the class
definition for TopicCompositionError to subclass OnexError, add or adjust the
import for OnexError, and keep the existing docstring; ensure any tests or
raises throughout the codebase still refer to TopicCompositionError but now get
the OnexError behavior for consistent project error-handling.

🧹 Nitpick comments (3)

src/omnibase_infra/services/mcp/service_mcp_tool_sync.py (1)

32-33: Consider updating the module docstring “Event Topic” to match the new constant.
If SUFFIX_NODE_REGISTRATION resolves to an ONEX topic, the top-level docstring still mentions node.registration.v1, which could mislead readers.

Also applies to: 80-82

tests/unit/topics/test_util_topic_composition.py (1)

21-25: Consider importing ENV_PREFIXES to avoid drift.

The hardcoded environment list ["dev", "staging", "prod", "test", "local"] could become out of sync if ENV_PREFIXES is updated in the source module. Consider importing the constant for consistency.

♻️ Suggested improvement

 from omnibase_infra.topics import (
     SUFFIX_NODE_INTROSPECTION,
     SUFFIX_NODE_REGISTRATION,
     TopicCompositionError,
     build_full_topic,
 )
+from omnibase_infra.topics.util_topic_composition import ENV_PREFIXES
 
 ...
 
     def test_build_full_topic_with_different_envs(self) -> None:
         """Should work with all valid environment prefixes."""
-        for env in ["dev", "staging", "prod", "test", "local"]:
+        for env in ENV_PREFIXES:
             topic = build_full_topic(env, "myapp", SUFFIX_NODE_INTROSPECTION)
             assert topic.startswith(f"{env}.myapp.")

src/omnibase_infra/mixins/mixin_node_introspection.py (1)

240-249: Consider relocating imports to the top of the file.

The topic constant imports are placed mid-file after the logger definition. While this works, Python convention is to place all imports at the module's top (after docstrings and __future__ imports). The current placement may have been intentional to separate "configuration constants" from "type imports", but it reduces discoverability.

♻️ Suggested relocation

Move these imports to the top import section (around lines 196-237) with a comment grouping:

# Topic defaults from canonical config (aliased for backward compatibility)
from omnibase_infra.models.discovery.model_introspection_config import (
    DEFAULT_HEARTBEAT_TOPIC as HEARTBEAT_TOPIC,
)
from omnibase_infra.models.discovery.model_introspection_config import (
    DEFAULT_INTROSPECTION_TOPIC as INTROSPECTION_TOPIC,
)
from omnibase_infra.models.discovery.model_introspection_config import (
    DEFAULT_REQUEST_INTROSPECTION_TOPIC as REQUEST_INTROSPECTION_TOPIC,
)

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Use OnexError for suffix validation failures.

Line 135-136 raises ValueError, but project guidelines require only OnexError (with error chaining). Please switch to OnexError and chain from an underlying exception to preserve context. As per coding guidelines, only OnexError (or subclasses) should be raised with raise ... from e.

✅ Proposed fix

-from omnibase_core.validation import validate_topic_suffix
+from omnibase_core.validation import validate_topic_suffix
+from omnibase_core.errors import OnexError
@@
     for suffix in ALL_PLATFORM_SUFFIXES:
         result = validate_topic_suffix(suffix)
         if not result.is_valid:
-            raise ValueError(
-                f"Invalid platform topic suffix '{suffix}': {result.error}"
-            )
+            err = ValueError(result.error)
+            raise OnexError(
+                f"Invalid platform topic suffix '{suffix}': {result.error}"
+            ) from err

🤖 Prompt for AI Agents

In `@src/omnibase_infra/topics/platform_topic_suffixes.py` around lines 125 - 137,
Replace the raised ValueError in _validate_all_suffixes with an OnexError and
chain it from an underlying exception to preserve context: if
validate_topic_suffix(suffix) returns not result.is_valid, construct a small
underlying Exception (e.g. Exception(result.error)) and then raise
OnexError(f"Invalid platform topic suffix '{suffix}': {result.error}") from that
exception; ensure OnexError is imported where _validate_all_suffixes,
validate_topic_suffix, and ALL_PLATFORM_SUFFIXES are referenced.

[jonahgabriel]

File naming convention violation: Per CLAUDE.md, files containing constants should be named constants_<name>.py. This file defines module-level constants (SUFFIX_NODE_REGISTRATION, etc.) and should be renamed.

The codebase shows 100% consistency with this pattern: constants_metrics.py, constants_notification.py, constants_dlq.py.

Fix: Rename platform_topic_suffixes.py to constants_platform_topic_suffixes.py and update all imports in omnibase_infra.topics package and consuming modules.