cleveragents/cleveragents-core

Fork 3

UAT: `errors.py` missing error code constants for DUPLICATE_ENTITY (-32005), BUDGET_EXCEEDED (-32006), and VERSION_MISMATCH (-32007) per ADR-047 #5577

New issue

Open

opened 2026-04-09 07:38:38 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 07:38:38 +00:00

Owner

Bug Report

Summary

src/cleveragents/a2a/errors.py documents error codes -32005 (Duplicate entity), -32006 (Budget exceeded), and -32007 (Version mismatch) in comments per ADR-047, but does NOT define them as module-level constants or map them in map_domain_error(). This creates an incomplete implementation of the ADR-047 error code taxonomy.

Evidence

From src/cleveragents/a2a/errors.py:

# Application-defined codes (per docs/reference/a2a.md §Error Code Taxonomy):
#   -32001  Resource not found
#   -32002  Authentication required
#   -32003  Authorization forbidden
#   -32004  Invalid state / business rule violation
#   -32005  Duplicate entity          ← documented but NOT defined as constant
#   -32006  Budget exceeded           ← documented but NOT defined as constant
#   -32007  Version mismatch          ← documented but NOT defined as constant
#   -32008  Plan error
#   -32009  Configuration error

The following constants are defined: NOT_FOUND, AUTH_ERROR, FORBIDDEN, INVALID_STATE, PLAN_ERROR, CONFIGURATION_ERROR, VALIDATION_ERROR, INTERNAL_ERROR.

The following constants are missing: DUPLICATE_ENTITY, BUDGET_EXCEEDED, VERSION_MISMATCH.

ADR-047 Specification

From ADR-047 §Error Code Mapping:

Code	Meaning	Domain Exception(s)
`-32005`	Already exists	`DuplicateEntityError`
`-32006`	Budget exceeded	`BudgetExceededError`
`-32007`	Version mismatch	`A2aVersionMismatchError`

Impact

Incomplete error taxonomy: Clients cannot distinguish "duplicate entity" from "internal error" — both return -32603
Budget enforcement gap: When budget enforcement is implemented (v3.6.0 deliverable #14), there is no error code to signal budget exceeded to clients
Version mismatch not mapped: A2aVersionMismatchError is defined in errors.py but not mapped in map_domain_error() — if raised, it would fall through to the generic INTERNAL_ERROR code instead of -32007
_a2a_code_map.py incomplete: The shared code map used in Behave tests also lacks these codes

Verified By

from cleveragents.a2a import errors as a2a_errors
assert hasattr(a2a_errors, 'DUPLICATE_ENTITY')  # AssertionError
assert hasattr(a2a_errors, 'BUDGET_EXCEEDED')    # AssertionError
assert hasattr(a2a_errors, 'VERSION_MISMATCH')   # AssertionError

Fix Required

Add missing constants to errors.py:

DUPLICATE_ENTITY: int = -32005
BUDGET_EXCEEDED: int = -32006
VERSION_MISMATCH: int = -32007

Add corresponding domain exception classes to core/exceptions.py:

class DuplicateEntityError(DomainError): ...
class BudgetExceededError(DomainError): ...

Map them in map_domain_error():

if isinstance(exc, DuplicateEntityError):
    return DUPLICATE_ENTITY, str(exc)
if isinstance(exc, BudgetExceededError):
    return BUDGET_EXCEEDED, str(exc)
if isinstance(exc, A2aVersionMismatchError):
    return VERSION_MISMATCH, str(exc)

Add to _a2a_code_map.py and __all__ in errors.py

Spec Reference

ADR-047 §Error Code Mapping
docs/reference/a2a.md §Error Code Taxonomy

Metadata

Commit message: fix(a2a): add missing DUPLICATE_ENTITY, BUDGET_EXCEEDED, VERSION_MISMATCH error code constants per ADR-047
Branch name: fix/m7-a2a-missing-error-codes

Subtasks

Add DUPLICATE_ENTITY = -32005, BUDGET_EXCEEDED = -32006, VERSION_MISMATCH = -32007 constants to errors.py
Add DuplicateEntityError and BudgetExceededError to core/exceptions.py
Map new exceptions in map_domain_error()
Map A2aVersionMismatchError to VERSION_MISMATCH in map_domain_error()
Update _a2a_code_map.py with new codes
Update __all__ in errors.py
Add Behave tests for new error code mappings

Definition of Done

All 9 error codes from ADR-047 are defined as constants in errors.py
map_domain_error() handles all corresponding domain exceptions
Behave tests cover the new error code mappings
nox passes

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report ### Summary `src/cleveragents/a2a/errors.py` documents error codes `-32005` (Duplicate entity), `-32006` (Budget exceeded), and `-32007` (Version mismatch) in comments per ADR-047, but does NOT define them as module-level constants or map them in `map_domain_error()`. This creates an incomplete implementation of the ADR-047 error code taxonomy. ### Evidence From `src/cleveragents/a2a/errors.py`: ```python # Application-defined codes (per docs/reference/a2a.md §Error Code Taxonomy): # -32001 Resource not found # -32002 Authentication required # -32003 Authorization forbidden # -32004 Invalid state / business rule violation # -32005 Duplicate entity ← documented but NOT defined as constant # -32006 Budget exceeded ← documented but NOT defined as constant # -32007 Version mismatch ← documented but NOT defined as constant # -32008 Plan error # -32009 Configuration error ``` The following constants are defined: `NOT_FOUND`, `AUTH_ERROR`, `FORBIDDEN`, `INVALID_STATE`, `PLAN_ERROR`, `CONFIGURATION_ERROR`, `VALIDATION_ERROR`, `INTERNAL_ERROR`. The following constants are **missing**: `DUPLICATE_ENTITY`, `BUDGET_EXCEEDED`, `VERSION_MISMATCH`. ### ADR-047 Specification From ADR-047 §Error Code Mapping: | Code | Meaning | Domain Exception(s) | |------|---------|---------------------| | `-32005` | Already exists | `DuplicateEntityError` | | `-32006` | Budget exceeded | `BudgetExceededError` | | `-32007` | Version mismatch | `A2aVersionMismatchError` | ### Impact 1. **Incomplete error taxonomy**: Clients cannot distinguish "duplicate entity" from "internal error" — both return `-32603` 2. **Budget enforcement gap**: When budget enforcement is implemented (v3.6.0 deliverable #14), there is no error code to signal budget exceeded to clients 3. **Version mismatch not mapped**: `A2aVersionMismatchError` is defined in `errors.py` but not mapped in `map_domain_error()` — if raised, it would fall through to the generic `INTERNAL_ERROR` code instead of `-32007` 4. **`_a2a_code_map.py` incomplete**: The shared code map used in Behave tests also lacks these codes ### Verified By ```python from cleveragents.a2a import errors as a2a_errors assert hasattr(a2a_errors, 'DUPLICATE_ENTITY') # AssertionError assert hasattr(a2a_errors, 'BUDGET_EXCEEDED') # AssertionError assert hasattr(a2a_errors, 'VERSION_MISMATCH') # AssertionError ``` ### Fix Required 1. Add missing constants to `errors.py`: ```python DUPLICATE_ENTITY: int = -32005 BUDGET_EXCEEDED: int = -32006 VERSION_MISMATCH: int = -32007 ``` 2. Add corresponding domain exception classes to `core/exceptions.py`: ```python class DuplicateEntityError(DomainError): ... class BudgetExceededError(DomainError): ... ``` 3. Map them in `map_domain_error()`: ```python if isinstance(exc, DuplicateEntityError): return DUPLICATE_ENTITY, str(exc) if isinstance(exc, BudgetExceededError): return BUDGET_EXCEEDED, str(exc) if isinstance(exc, A2aVersionMismatchError): return VERSION_MISMATCH, str(exc) ``` 4. Add to `_a2a_code_map.py` and `__all__` in `errors.py` ### Spec Reference - ADR-047 §Error Code Mapping - `docs/reference/a2a.md` §Error Code Taxonomy ### Metadata - **Commit message**: `fix(a2a): add missing DUPLICATE_ENTITY, BUDGET_EXCEEDED, VERSION_MISMATCH error code constants per ADR-047` - **Branch name**: `fix/m7-a2a-missing-error-codes` ## Subtasks - [ ] Add `DUPLICATE_ENTITY = -32005`, `BUDGET_EXCEEDED = -32006`, `VERSION_MISMATCH = -32007` constants to `errors.py` - [ ] Add `DuplicateEntityError` and `BudgetExceededError` to `core/exceptions.py` - [ ] Map new exceptions in `map_domain_error()` - [ ] Map `A2aVersionMismatchError` to `VERSION_MISMATCH` in `map_domain_error()` - [ ] Update `_a2a_code_map.py` with new codes - [ ] Update `__all__` in `errors.py` - [ ] Add Behave tests for new error code mappings ## Definition of Done - All 9 error codes from ADR-047 are defined as constants in `errors.py` - `map_domain_error()` handles all corresponding domain exceptions - Behave tests cover the new error code mappings - `nox` passes --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 07:39:46 +00:00

HAL9000 added this to the v3.5.0 milestone

2026-04-09 07:45:49 +00:00

HAL9000 commented

2026-04-09 07:46:20 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 added

and removed

labels

2026-04-09 07:46:23 +00:00

HAL9000 referenced this issue

2026-04-09 07:47:09 +00:00

[AUTO-PROJ-OWN] Project Owner Report (Cycle 27) #5570

HAL9000 added a new dependency

2026-04-09 07:58:37 +00:00

#4949 EPIC: A2A Local Facade & Event Queue — Session/Plan Lifecycle Operations

HAL9000 commented

2026-04-09 08:00:06 +00:00

Author

Owner

Hierarchical Compliance Fix: This issue was detected as an orphan (no parent Epic).

Solution: Linked to Epic #4949 (A2A Local Facade & Event Queue — Session/Plan Lifecycle Operations) as A2A error code constants are part of the A2A protocol implementation scope.

Hierarchy: Issue #5577 → Epic #4949 → Legendary #4944

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Hierarchical Compliance Fix**: This issue was detected as an orphan (no parent Epic). **Solution**: Linked to Epic #4949 (A2A Local Facade & Event Queue — Session/Plan Lifecycle Operations) as A2A error code constants are part of the A2A protocol implementation scope. **Hierarchy**: Issue #5577 → Epic #4949 → Legendary #4944 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner

HAL9000 referenced this issue

2026-04-09 08:00:42 +00:00

[AUTO-EPIC] Epic Planning Health Report (Cycle 12) #5422