Lack of Type Safety in Actor.config_blob and Actor.compiled_metadata #8260

New issue

Open

opened 2026-04-13 06:49:56 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-13 06:49:56 +00:00

Owner

Metadata

Commit Message: refactor(core): improve type safety of Actor.config_blob and Actor.compiled_metadata
Branch Name: refactor/actor-type-safety

Background and Context

The Actor model in src/cleveragents/domain/models/core/actor.py has two fields, config_blob and compiled_metadata, that are of type dict[str, Any].

Using dict[str, Any] is not very type-safe and can lead to runtime errors if the data in these fields is not in the expected format. It also makes the code harder to understand and maintain, as it's not clear what the expected structure of the data is.

Expected Behavior

The config_blob and compiled_metadata fields should use more specific types if possible. If the structure of the data is known, it should be defined using Pydantic models. If the structure is dynamic, it should be documented, and validation should be added to ensure that the data is in the expected format.

Acceptance Criteria

The config_blob and compiled_metadata fields in the Actor model use more specific types than dict[str, Any].
The new types are well-documented and validated.
The changes are covered by unit tests.

Subtasks

Audit current usages of Actor.config_blob and Actor.compiled_metadata across the codebase to understand the actual data shapes in use.
Determine whether the structure is static (define Pydantic models) or dynamic (add runtime validation + documentation).
Define and implement the new types (Pydantic models or TypedDict) for config_blob and compiled_metadata.
Update the Actor model to use the new types.
Update all call sites that read from or write to these fields to use the new types.
Add or update unit tests to cover the new types and validation logic.
Update docstrings and inline documentation to reflect the new types.

Definition of Done

This issue should be closed when:

Actor.config_blob and Actor.compiled_metadata no longer use dict[str, Any] as their type.
The new types are validated (either via Pydantic model constraints or explicit runtime checks).
All existing tests pass and new tests cover the refactored fields.
Code review has been completed and approved.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `refactor(core): improve type safety of Actor.config_blob and Actor.compiled_metadata` - **Branch Name**: `refactor/actor-type-safety` ## Background and Context The `Actor` model in `src/cleveragents/domain/models/core/actor.py` has two fields, `config_blob` and `compiled_metadata`, that are of type `dict[str, Any]`. Using `dict[str, Any]` is not very type-safe and can lead to runtime errors if the data in these fields is not in the expected format. It also makes the code harder to understand and maintain, as it's not clear what the expected structure of the data is. ## Expected Behavior The `config_blob` and `compiled_metadata` fields should use more specific types if possible. If the structure of the data is known, it should be defined using Pydantic models. If the structure is dynamic, it should be documented, and validation should be added to ensure that the data is in the expected format. ## Acceptance Criteria - The `config_blob` and `compiled_metadata` fields in the `Actor` model use more specific types than `dict[str, Any]`. - The new types are well-documented and validated. - The changes are covered by unit tests. ## Subtasks - [ ] Audit current usages of `Actor.config_blob` and `Actor.compiled_metadata` across the codebase to understand the actual data shapes in use. - [ ] Determine whether the structure is static (define Pydantic models) or dynamic (add runtime validation + documentation). - [ ] Define and implement the new types (Pydantic models or TypedDict) for `config_blob` and `compiled_metadata`. - [ ] Update the `Actor` model to use the new types. - [ ] Update all call sites that read from or write to these fields to use the new types. - [ ] Add or update unit tests to cover the new types and validation logic. - [ ] Update docstrings and inline documentation to reflect the new types. ## Definition of Done This issue should be closed when: - `Actor.config_blob` and `Actor.compiled_metadata` no longer use `dict[str, Any]` as their type. - The new types are validated (either via Pydantic model constraints or explicit runtime checks). - All existing tests pass and new tests cover the refactored fields. - Code review has been completed and approved. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added this to the v3.2.0 milestone

2026-04-13 06:50:38 +00:00

HAL9000 commented

2026-04-13 06:52:52 +00:00

Author

Owner

[AUTO-EPIC] Epic Linkage

This issue is a child of Epic #8043 — M3 UAT Bug Resolution — Spec Alignment Backlog (v3.2.0).

Type safety issues in Actor.config_blob and Actor.compiled_metadata are code quality issues that fall under the M3 UAT bug resolution scope.

Dependency direction: This issue (#8260) BLOCKS Epic #8043.

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

## [AUTO-EPIC] Epic Linkage This issue is a child of **Epic #8043** — M3 UAT Bug Resolution — Spec Alignment Backlog (v3.2.0). Type safety issues in Actor.config_blob and Actor.compiled_metadata are code quality issues that fall under the M3 UAT bug resolution scope. **Dependency direction**: This issue (#8260) BLOCKS Epic #8043. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

HAL9000 added the

labels

2026-04-13 07:00:14 +00:00

HAL9000 referenced this issue

2026-04-13 07:10:16 +00:00

[AUTO-EPIC] Status: Epic Planning Supervisor — Cycle 10 #8273