CHORUS/docs/decisions/2025-09-06-refactor-chorus.md

ucxl.address: ucxl://arbiter:refactor@CHORUS:refactor-chorus/#/docs/decisions/2025-09-06-refactor-chorus.md version: 2025-09-06T00:00:00Z content_type: text/markdown metadata: classification: internal roles: [arbiter, maintainer]

Decision Record: Refactor BZZZ references to CHORUS

Problem

Legacy references to the former module name “BZZZ” (and lowercase “bzzz”) exist across the CHORUS codebase. These cause inconsistency in env vars, identifiers, topics, and docs now that CHORUS is the canonical name. We need consistent naming for clarity and to avoid misconfiguration.

Options considered

1. Targeted rename only in source code (keep docs/env examples unchanged)

   • Pros: Minimizes risk of breaking external setups
   • Cons: Leaves inconsistency; increases confusion

2. Global textual refactor of tokens (BZZZ→CHORUS, bzzz→chorus) across project code and docs, excluding vendor/generated assets

   • Pros: Consistent naming; straightforward and auditable
   • Cons: May require updating external env files and scripts that referenced old names

3. Dual-support via compatibility layer/env fallback (accept both BZZZ_* and CHORUS_*) temporarily

   • Pros: Backwards compatible
   • Cons: Adds complexity; requires additional code paths and deprecation plan

Decision

Adopt Option 2 now: perform a safe, in-place textual refactor of tokens “BZZZ”→“CHORUS” and “bzzz”→“chorus” throughout CHORUS code and docs. Exclude vendor and generated web assets to avoid unintended binary changes. Commit and push as a single change set.

Scope boundaries:

• Include: Go sources, tests, README/MD, API scaffolding, YAML-in-code templates
• Exclude: vendor/**, pkg/web/static/_next/** bundles

Impact

• Env var names and topic constants now use CHORUS; external deployments that relied on BZZZ_* should update to CHORUS_* equivalents.
• No functional behavior intended to change; this is a rename-only refactor.
• Rollback: revert commit b6634e4 if downstream issues arise; consider Option 3 for short-term compat if needed.

Evidence

• Commit: b6634e4 “refactor CHORUS”
• Gitea: https://gitea.chorus.services/tony/CHORUS/commit/b6634e4
• Search baseline: 21 files originally contained BZZZ/bzzz tokens (rg scan).