cleanup: Remove dead build_full_topic and enforce realm-agnostic topic invariant

[jonahgabriel]

Summary

• Deletes build_full_topic() (util_topic_composition.py) — zero callers in src/ since OMN-1972 established TopicResolver as the canonical pass-through resolver. The function composed {env}.{namespace}.{suffix} topics, an explicitly invalid pattern now
• Deletes 191 lines of tests (test_util_topic_composition.py) that only exercised dead code
• Removes dead exports (build_full_topic, TopicCompositionError, MAX_NAMESPACE_LENGTH) from topics/__init__.py
• Adds IMPORTANT docstring in topics/__init__.py and topic_constants.py: environment prefixes must NOT appear on the wire; isolation enforced via envelope identity and consumer group naming
• Clarifies DLQ exception: DLQ topics (<env>.dlq.<category>.<version>) are the sole legitimate use of env prefixes — they're per-environment infrastructure storage, not event routing

Why

Leaving build_full_topic exported was a footgun. It encoded a pattern that the architecture explicitly abandoned, and cargo-culting from its examples would reintroduce dev.-prefixed topics that no consumer expects. Burning this bridge prevents drift.

Test plan

• poetry run pytest tests/unit/topics/ -xvs — 40 passed (TopicResolver + platform suffix tests)
• poetry run pytest tests/ -x -n auto — 3726 passed (5 pre-existing infra failures unrelated to this change)
• rg "build_full_topic" src/ tests/ — zero hits
• All pre-commit hooks pass (including mypy, ruff, architecture validation)

Summary by CodeRabbit

• Documentation

  • Clarified DLQ topic naming, canonical format, environment prefix handling on the wire, and validation guidance.

• Refactor

  • Removed legacy topic composition utilities and related validation/test coverage, reducing the public topic-API surface and clarifying that topic resolution is handled centrally (realm-agnostic handling, canonical suffixes).

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This PR removes the topic composition utilities module and its tests, updates package exports to drop composition helpers, and updates docstrings/examples for DLQ topic naming and guidance to use TopicResolver for canonical topic handling.

Changes

Cohort / File(s)	Summary
DLQ docs & constants src/omnibase_infra/event_bus/topic_constants.py	Rewrote module docstring and examples to clarify DLQ topic naming (<env>.dlq.<category>.<version>), wiring/environment prefix guidance, and wiring health monitoring constants; no functional code changes.
Public API export changes src/omnibase_infra/topics/__init__.py	Removed exports of build_full_topic, TopicCompositionError, and MAX_NAMESPACE_LENGTH; added guidance that topics are realm-agnostic and resolution should use TopicResolver.
Removed topic composition utilities src/omnibase_infra/topics/util_topic_composition.py	Deleted entire module including build_full_topic, TopicCompositionError, MAX_NAMESPACE_LENGTH, and associated validation logic and docstrings.
Tests removed tests/unit/topics/test_util_topic_composition.py	Deleted full test suite for topic composition utilities (validation, error behavior, edge cases).
Minor doc reference edit src/omnibase_infra/topics/topic_resolver.py	Removed a "See Also" reference to the removed util module from the module docstring; no behavioral changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(OMN-1972): Add canonical TopicResolver and declarative orchestrator subscriptions #253: Introduces canonical TopicResolver and replaces scattered composition logic; touches the same topic composition/resolution area.

Poem

🐇 I hopped through code and cleared the brush away,
Removed the old compose-tools so topics find their way,
DLQs now named tidy, examples crisp and bright,
TopicResolver guides them home each day and night,
Thump-thump—new docs hopped in, and everything's alright! 🥕

🚥 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 summarizes the main objectives: removing the dead build_full_topic function and enforcing the realm-agnostic topic invariant. It directly reflects both primary changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch cleanup/remove-dead-build-full-topic

---

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