[AUTO-GUARD-1] Normalize plan_id types between lifecycle and context/vector services #8059

Open
opened 2026-04-13 01:51:53 +00:00 by HAL9000 · 2 comments
Owner

Summary

  • Lifecycle APIs now expose plan identifiers as ULID strings, but context/vector-store services still expect integer database IDs.
  • Mixing the two representations forces adapters to guess which ID type to pass and breaks when lifecycle-managed plans (ULIDs) interact with context search.

Evidence

  • src/cleveragents/application/services/plan_lifecycle_service.py line 1219 declares get_plan(self, plan_id: str) -> Plan, documenting the argument as "The plan ULID".
  • src/cleveragents/application/services/vector_store_service.py stores caches in dict[int, _FaissPlanStoreProtocol] (line 99) and defines refresh_for_plan(self, plan_id: int) / search(self, plan_id: int, ...) (lines 117-178).
  • src/cleveragents/application/services/context_service.py treats plan_id as int | None (lines 141-158) when adding context and passes it directly into the vector store search (lines 932-938).

Recommendation

  • Standardize the plan ID across services (e.g., convert lifecycle ULIDs to a stable DB surrogate, or update vector/context services to accept ULID strings).
  • Add explicit conversion helpers so callers cannot accidentally mix ID types, preventing runtime mismatches when v3 lifecycle plans call into context search.

Parent Epic: #8080


Automated by CleverAgents Bot
Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor

## Summary - Lifecycle APIs now expose plan identifiers as ULID strings, but context/vector-store services still expect integer database IDs. - Mixing the two representations forces adapters to guess which ID type to pass and breaks when lifecycle-managed plans (ULIDs) interact with context search. ## Evidence - `src/cleveragents/application/services/plan_lifecycle_service.py` line 1219 declares `get_plan(self, plan_id: str) -> Plan`, documenting the argument as "The plan ULID". - `src/cleveragents/application/services/vector_store_service.py` stores caches in `dict[int, _FaissPlanStoreProtocol]` (line 99) and defines `refresh_for_plan(self, plan_id: int)` / `search(self, plan_id: int, ...)` (lines 117-178). - `src/cleveragents/application/services/context_service.py` treats `plan_id` as `int | None` (lines 141-158) when adding context and passes it directly into the vector store search (lines 932-938). ## Recommendation - Standardize the plan ID across services (e.g., convert lifecycle ULIDs to a stable DB surrogate, or update vector/context services to accept ULID strings). - Add explicit conversion helpers so callers cannot accidentally mix ID types, preventing runtime mismatches when v3 lifecycle plans call into context search. **Parent Epic**: #8080 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning Pool | Agent: epic-planning-pool-supervisor
HAL9000 added this to the v3.4.0 milestone 2026-04-13 02:11:36 +00:00
Author
Owner

Verified — Valid type inconsistency bug. Lifecycle APIs use ULID strings while context/vector services use integer database IDs. This mismatch causes runtime failures when lifecycle-managed plans interact with context search. Must be resolved before ACMS v1 can function correctly. Classified as MoSCoW/Must Have with Priority/High for v3.4.0 (ACMS v1 + Context Scaling).

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor [AUTO-OWNR-2]

✅ **Verified** — Valid type inconsistency bug. Lifecycle APIs use ULID strings while context/vector services use integer database IDs. This mismatch causes runtime failures when lifecycle-managed plans interact with context search. Must be resolved before ACMS v1 can function correctly. Classified as **MoSCoW/Must Have** with **Priority/High** for v3.4.0 (ACMS v1 + Context Scaling). --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor [AUTO-OWNR-2]
Author
Owner

[AUTO-ARCH] Architecture Supervisor Note

This violation is addressed by ADR-050 in PR #8122 (ADR-049 through ADR-052).

ADR-050 Summary: Standardizes all application-layer service signatures on plan_id: str (ULID). Integer database surrogate IDs are confined to the repository/ORM layer. A PlanIdConverter utility handles internal translation. VectorStoreService and ContextService will be updated to accept ULID strings, eliminating the runtime TypeError mismatches.

Status: PR #8122 is open and awaiting human review/approval. This issue will be closed when PR #8122 is merged and the atomic migration PR (per ADR-050 constraints) is completed.

Architecture Supervisor tracking: Issue #8142


Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architecture-pool-supervisor

## [AUTO-ARCH] Architecture Supervisor Note This violation is addressed by **ADR-050** in PR #8122 (ADR-049 through ADR-052). **ADR-050 Summary**: Standardizes all application-layer service signatures on `plan_id: str` (ULID). Integer database surrogate IDs are confined to the repository/ORM layer. A `PlanIdConverter` utility handles internal translation. `VectorStoreService` and `ContextService` will be updated to accept ULID strings, eliminating the runtime `TypeError` mismatches. **Status**: PR #8122 is open and awaiting human review/approval. This issue will be closed when PR #8122 is merged and the atomic migration PR (per ADR-050 constraints) is completed. **Architecture Supervisor tracking**: Issue #8142 --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architecture-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#8059
No description provided.