Refactor: `uuid.uuid4()` used for thread IDs in application services — should use ULIDs for consistency #10317

New issue

Open

opened 2026-04-18 08:41:27 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-18 08:41:27 +00:00

Owner

Metadata

Commit message: refactor(application): replace uuid4 thread ID generation with ULID for consistency
Branch name: feature/refactor-uuid-to-ulid-thread-ids

Background and Context

An automated architecture guard scan on 2026-04-18 found two uses of uuid.uuid4() in application layer services for generating thread IDs. The project uses ULIDs (Universally Unique Lexicographically Sortable Identifiers) as its standard identifier format for domain entities. Using uuid.uuid4() for any identifier generation creates inconsistency and bypasses the ULID's lexicographic sortability advantage.

Affected locations:

File	Line	Code
`application/services/context_service.py`	591	`config["configurable"]["thread_id"] = f"context-analysis-{uuid.uuid4()}"`
`application/services/plan_service.py`	578	`config["configurable"]["thread_id"] = f"{thread_prefix}-{uuid.uuid4()}"`

Current Behavior

Thread IDs for LangGraph configurable contexts are generated using uuid.uuid4():

# context_service.py:591
config["configurable"]["thread_id"] = f"context-analysis-{uuid.uuid4()}"

# plan_service.py:578
config["configurable"]["thread_id"] = f"{thread_prefix}-{uuid.uuid4()}"

This produces non-sortable, non-monotonic identifiers that are inconsistent with the project's ULID standard.

Expected Behavior

Thread IDs should be generated using the project's standard ULID library:

from cleveragents.shared.ulid import new_ulid  # or equivalent

# context_service.py
config["configurable"]["thread_id"] = f"context-analysis-{new_ulid()}"

# plan_service.py
config["configurable"]["thread_id"] = f"{thread_prefix}-{new_ulid()}"

This ensures all generated identifiers are lexicographically sortable, monotonically increasing within the same millisecond, and consistent with the rest of the codebase.

Acceptance Criteria

No uuid.uuid4() calls remain in src/cleveragents/application/ or src/cleveragents/domain/
Thread IDs in context_service.py and plan_service.py use the project's ULID generation utility
The ULID-generated thread IDs remain compatible with LangGraph's configurable context requirements
All existing Behave scenarios continue to pass
Coverage remains ≥ 97%

Supporting Information

Scan date: 2026-04-18
Scan tool: Architecture Guard Worker (automated)
Affected files: application/services/context_service.py:591, application/services/plan_service.py:578
Note: These are thread IDs for LangGraph configurable contexts, not domain entity IDs — verify that LangGraph accepts ULID-format strings as thread IDs before replacing

Subtasks

Identify the project's canonical ULID generation utility (check src/cleveragents/shared/ or src/cleveragents/core/)
Verify LangGraph accepts ULID-format strings as thread_id in configurable contexts
Replace uuid.uuid4() in context_service.py:591 with ULID generation
Replace uuid.uuid4() in plan_service.py:578 with ULID generation
Remove import uuid from both files if no longer needed
Tests (Behave): Verify context analysis and plan service scenarios still pass
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
No uuid.uuid4() calls exist in src/cleveragents/application/ or src/cleveragents/domain/.
A Git commit is created where the first line matches the Commit Message in Metadata exactly, followed by a blank line, then additional details.
The commit is pushed to the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by Architecture Guard Worker — scan date 2026-04-18

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit message:** `refactor(application): replace uuid4 thread ID generation with ULID for consistency` - **Branch name:** `feature/refactor-uuid-to-ulid-thread-ids` ## Background and Context An automated architecture guard scan on 2026-04-18 found two uses of `uuid.uuid4()` in application layer services for generating thread IDs. The project uses ULIDs (Universally Unique Lexicographically Sortable Identifiers) as its standard identifier format for domain entities. Using `uuid.uuid4()` for any identifier generation creates inconsistency and bypasses the ULID's lexicographic sortability advantage. **Affected locations:** | File | Line | Code | |------|------|------| | `application/services/context_service.py` | 591 | `config["configurable"]["thread_id"] = f"context-analysis-{uuid.uuid4()}"` | | `application/services/plan_service.py` | 578 | `config["configurable"]["thread_id"] = f"{thread_prefix}-{uuid.uuid4()}"` | ## Current Behavior Thread IDs for LangGraph configurable contexts are generated using `uuid.uuid4()`: ```python # context_service.py:591 config["configurable"]["thread_id"] = f"context-analysis-{uuid.uuid4()}" # plan_service.py:578 config["configurable"]["thread_id"] = f"{thread_prefix}-{uuid.uuid4()}" ``` This produces non-sortable, non-monotonic identifiers that are inconsistent with the project's ULID standard. ## Expected Behavior Thread IDs should be generated using the project's standard ULID library: ```python from cleveragents.shared.ulid import new_ulid # or equivalent # context_service.py config["configurable"]["thread_id"] = f"context-analysis-{new_ulid()}" # plan_service.py config["configurable"]["thread_id"] = f"{thread_prefix}-{new_ulid()}" ``` This ensures all generated identifiers are lexicographically sortable, monotonically increasing within the same millisecond, and consistent with the rest of the codebase. ## Acceptance Criteria - [ ] No `uuid.uuid4()` calls remain in `src/cleveragents/application/` or `src/cleveragents/domain/` - [ ] Thread IDs in `context_service.py` and `plan_service.py` use the project's ULID generation utility - [ ] The ULID-generated thread IDs remain compatible with LangGraph's configurable context requirements - [ ] All existing Behave scenarios continue to pass - [ ] Coverage remains ≥ 97% ## Supporting Information - Scan date: 2026-04-18 - Scan tool: Architecture Guard Worker (automated) - Affected files: `application/services/context_service.py:591`, `application/services/plan_service.py:578` - Note: These are thread IDs for LangGraph configurable contexts, not domain entity IDs — verify that LangGraph accepts ULID-format strings as thread IDs before replacing ## Subtasks - [ ] Identify the project's canonical ULID generation utility (check `src/cleveragents/shared/` or `src/cleveragents/core/`) - [ ] Verify LangGraph accepts ULID-format strings as `thread_id` in configurable contexts - [ ] Replace `uuid.uuid4()` in `context_service.py:591` with ULID generation - [ ] Replace `uuid.uuid4()` in `plan_service.py:578` with ULID generation - [ ] Remove `import uuid` from both files if no longer needed - [ ] Tests (Behave): Verify context analysis and plan service scenarios still pass - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - No `uuid.uuid4()` calls exist in `src/cleveragents/application/` or `src/cleveragents/domain/`. - A Git commit is created where the first line matches the Commit Message in Metadata exactly, followed by a blank line, then additional details. - The commit is pushed to the branch matching the Branch in Metadata exactly. - The commit is submitted as a pull request to `master`, reviewed, and merged before this issue is marked done. --- *Automated by Architecture Guard Worker — scan date 2026-04-18* --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-18 08:42:37 +00:00

HAL9000 referenced this issue

2026-04-18 08:51:02 +00:00

[AUTO-GUARD] Architecture Guard Status — Cycle 4 #10287