cleveragents/cleveragents-core

Fork 3

[Bug Hunt][Cycle 2][Config] Environment variable name collisions in key normalization #7141

New issue

Open

opened 2026-04-10 08:10:17 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-10 08:10:17 +00:00

Owner

Metadata

Branch: fix/bug-hunt-cycle2/config-env-var-name-collision
Commit Message: fix(config): prevent env var name collisions in _env_name() key normalization
Milestone: None (Backlog)
Parent Epic: #5502

Backlog note: This issue was discovered during autonomous operation
on milestone v3.2.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background

The configuration service's _env_name() function normalises both dots (.) and dashes (-) to underscores (_) when building environment variable names. This creates a collision space where distinct configuration keys map to the same environment variable name, causing silent configuration ambiguity and potential wrong-value application.

Current Behavior

# src/cleveragents/application/services/config_service.py, lines 87–94
def _env_name(section: str, key: str) -> str:
    """Build ``CLEVERAGENTS_<SECTION>_<KEY>`` environment variable name.

    Dots and dashes in *section* and *key* are normalised to underscores
    so that ``core.log.level`` becomes ``CLEVERAGENTS_CORE_LOG_LEVEL``.
    """
    raw = f"CLEVERAGENTS_{section}_{key}"
    return raw.upper().replace(".", "_").replace("-", "_")

Keys such as core.log-level and core.log_level both produce CLEVERAGENTS_CORE_LOG_LEVEL, making it impossible to distinguish which configuration key an environment variable override is intended for. The last registered key wins silently, with no warning or error.

Expected Behavior

Every distinct configuration key must produce a unique environment variable name. The normalization scheme must be injective (one-to-one): no two different (section, key) pairs may produce the same environment variable name.

Suggested approaches (in order of preference):

Double-underscore for dots, single underscore for dashes — core.log-level → CLEVERAGENTS_CORE__LOG_LEVEL vs core.log_level → CLEVERAGENTS_CORE__LOG__LEVEL. Preserves readability and is collision-free for the common case.
Collision registry with startup warning/error — detect and raise at registration time if two keys would produce the same env var name.
Hash suffix — append a short deterministic hash to disambiguate; less ergonomic but fully collision-proof.

Severity Assessment

Impact: Configuration keys with different names could map to the same environment variable, causing wrong values to be silently applied — a correctness and reliability issue.
Likelihood: Medium — likely to occur in systems with many configuration keys that use both dots and dashes as separators.
Priority: High

Location

File: src/cleveragents/application/services/config_service.py
Function: _env_name()
Lines: 87–94

Acceptance Criteria

_env_name() produces unique environment variable names for all distinct (section, key) pairs
Keys using dots, dashes, and underscores in different combinations do not collide
Existing valid env var names (e.g., CLEVERAGENTS_CORE_LOG_LEVEL for core.log.level) remain stable or a migration path is documented
A collision detection mechanism (registry check or normalization scheme) is in place at registration time
BDD scenarios cover the collision cases explicitly

Subtasks

Audit all existing _register() calls to identify any currently colliding keys
Design and implement a collision-free normalization scheme in _env_name()
Update _register() to detect and raise on collision at registration time
Update all affected BDD feature files and step definitions
Update documentation and docstrings to reflect the new normalization scheme
Ensure all nox stages pass

Definition of Done

_env_name() is injective: no two distinct (section, key) pairs produce the same env var name
Collision detection raises a clear error at registration time if a collision is introduced
BDD scenarios cover dot-only, dash-only, underscore-only, and mixed-separator key names
All nox stages pass
Coverage >= 97%

TDD Note

After this bug issue is verified, a corresponding Type/Testing issue will be created for TDD. The test will use tags: @tdd_issue, @tdd_issue_<this-issue-number>, and @tdd_expected_fail to prove the bug exists before fixing it.

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: new-issue-creator

## Metadata - **Branch**: `fix/bug-hunt-cycle2/config-env-var-name-collision` - **Commit Message**: `fix(config): prevent env var name collisions in _env_name() key normalization` - **Milestone**: None (Backlog) - **Parent Epic**: #5502 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.2.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Background The configuration service's `_env_name()` function normalises both dots (`.`) and dashes (`-`) to underscores (`_`) when building environment variable names. This creates a collision space where distinct configuration keys map to the same environment variable name, causing silent configuration ambiguity and potential wrong-value application. ## Current Behavior ```python # src/cleveragents/application/services/config_service.py, lines 87–94 def _env_name(section: str, key: str) -> str: """Build ``CLEVERAGENTS_<SECTION>_<KEY>`` environment variable name. Dots and dashes in *section* and *key* are normalised to underscores so that ``core.log.level`` becomes ``CLEVERAGENTS_CORE_LOG_LEVEL``. """ raw = f"CLEVERAGENTS_{section}_{key}" return raw.upper().replace(".", "_").replace("-", "_") ``` Keys such as `core.log-level` and `core.log_level` both produce `CLEVERAGENTS_CORE_LOG_LEVEL`, making it impossible to distinguish which configuration key an environment variable override is intended for. The last registered key wins silently, with no warning or error. ## Expected Behavior Every distinct configuration key must produce a unique environment variable name. The normalization scheme must be injective (one-to-one): no two different `(section, key)` pairs may produce the same environment variable name. Suggested approaches (in order of preference): 1. **Double-underscore for dots, single underscore for dashes** — `core.log-level` → `CLEVERAGENTS_CORE__LOG_LEVEL` vs `core.log_level` → `CLEVERAGENTS_CORE__LOG__LEVEL`. Preserves readability and is collision-free for the common case. 2. **Collision registry with startup warning/error** — detect and raise at registration time if two keys would produce the same env var name. 3. **Hash suffix** — append a short deterministic hash to disambiguate; less ergonomic but fully collision-proof. ## Severity Assessment - **Impact**: Configuration keys with different names could map to the same environment variable, causing wrong values to be silently applied — a correctness and reliability issue. - **Likelihood**: Medium — likely to occur in systems with many configuration keys that use both dots and dashes as separators. - **Priority**: High ## Location - **File**: `src/cleveragents/application/services/config_service.py` - **Function**: `_env_name()` - **Lines**: 87–94 ## Acceptance Criteria - [ ] `_env_name()` produces unique environment variable names for all distinct `(section, key)` pairs - [ ] Keys using dots, dashes, and underscores in different combinations do not collide - [ ] Existing valid env var names (e.g., `CLEVERAGENTS_CORE_LOG_LEVEL` for `core.log.level`) remain stable or a migration path is documented - [ ] A collision detection mechanism (registry check or normalization scheme) is in place at registration time - [ ] BDD scenarios cover the collision cases explicitly ## Subtasks - [ ] Audit all existing `_register()` calls to identify any currently colliding keys - [ ] Design and implement a collision-free normalization scheme in `_env_name()` - [ ] Update `_register()` to detect and raise on collision at registration time - [ ] Update all affected BDD feature files and step definitions - [ ] Update documentation and docstrings to reflect the new normalization scheme - [ ] Ensure all nox stages pass ## Definition of Done - [ ] `_env_name()` is injective: no two distinct `(section, key)` pairs produce the same env var name - [ ] Collision detection raises a clear error at registration time if a collision is introduced - [ ] BDD scenarios cover dot-only, dash-only, underscore-only, and mixed-separator key names - [ ] All nox stages pass - [ ] Coverage >= 97% ### TDD Note After this bug issue is verified, a corresponding `Type/Testing` issue will be created for TDD. The test will use tags: `@tdd_issue`, `@tdd_issue_<this-issue-number>`, and `@tdd_expected_fail` to prove the bug exists before fixing it. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: new-issue-creator

HAL9000 added the

labels

2026-04-10 08:10:55 +00:00

HAL9000 added a new dependency

2026-04-10 08:11:26 +00:00

#5502 EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0)

HAL9000 referenced this issue

2026-04-10 08:37:30 +00:00

[AUTO-BUG-POOL] Bug Hunt Worker 10 Summary Report #7183

HAL9000 added

and removed

labels

2026-04-14 06:49:04 +00:00

HAL9000 commented

2026-04-14 06:49:04 +00:00

Author

Owner

✅ Verified — Bug: environment variable name collisions in key normalization. MoSCoW: Should-have. Priority: Medium.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Bug: environment variable name collisions in key normalization. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor