Limited Type Safety in Resource.properties #8277

New issue

Open

opened 2026-04-13 07:26:30 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-13 07:26:30 +00:00

Owner

Metadata

Commit Message: refactor(core): improve type safety of Resource.properties
Branch Name: refactor/resource-properties-type-safety

Background and Context

The Resource model in src/cleveragents/domain/models/core/resource.py has a properties field typed as dict[str, str | int | float | bool | None]. While this is more specific than dict[str, Any], it remains insufficiently type-safe. Any string key is permitted and the value can be any of several primitive types, making it impossible to know at compile time what properties are expected for a given resource type. This ambiguity increases the risk of runtime errors, makes the API harder to use correctly, and reduces the value of static analysis tooling.

Expected Behavior

The properties field should use a more structured approach to define the possible properties for different resource types. This could be achieved using a discriminated union of Pydantic models, where each model represents the properties for a specific resource type. The result should be fully validated by Pydantic, well-documented, and statically analysable by tools such as Pyright.

Acceptance Criteria

The properties field in the Resource model uses a more structured and type-safe approach (e.g., a discriminated union of Pydantic models).
The new approach is well-documented with docstrings and/or inline comments.
Pydantic validation covers all defined resource property types.
The changes are covered by unit tests with coverage ≥ 97%.
Static type checking (Pyright) passes with no new errors introduced.

Subtasks

Audit all existing usages of Resource.properties across the codebase to understand current key/value patterns.
Design a discriminated union of Pydantic models representing each resource type's properties.
Refactor Resource.properties to use the new typed model.
Update all call sites that construct or access Resource.properties.
Add/update unit tests to cover the new property models and validation behaviour.
Verify Pyright passes with no new type errors.
Update relevant documentation and docstrings.

Definition of Done

This issue should be closed when:

The Resource.properties field is replaced with a structured, type-safe Pydantic model approach.
All existing tests continue to pass and new tests cover the refactored code.
Pyright reports no new type errors.
The PR has been reviewed, approved, and merged into the target branch.

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `refactor(core): improve type safety of Resource.properties` - **Branch Name**: `refactor/resource-properties-type-safety` ## Background and Context The `Resource` model in `src/cleveragents/domain/models/core/resource.py` has a `properties` field typed as `dict[str, str | int | float | bool | None]`. While this is more specific than `dict[str, Any]`, it remains insufficiently type-safe. Any string key is permitted and the value can be any of several primitive types, making it impossible to know at compile time what properties are expected for a given resource type. This ambiguity increases the risk of runtime errors, makes the API harder to use correctly, and reduces the value of static analysis tooling. ## Expected Behavior The `properties` field should use a more structured approach to define the possible properties for different resource types. This could be achieved using a discriminated union of Pydantic models, where each model represents the properties for a specific resource type. The result should be fully validated by Pydantic, well-documented, and statically analysable by tools such as Pyright. ## Acceptance Criteria - The `properties` field in the `Resource` model uses a more structured and type-safe approach (e.g., a discriminated union of Pydantic models). - The new approach is well-documented with docstrings and/or inline comments. - Pydantic validation covers all defined resource property types. - The changes are covered by unit tests with coverage ≥ 97%. - Static type checking (Pyright) passes with no new errors introduced. ## Subtasks - [ ] Audit all existing usages of `Resource.properties` across the codebase to understand current key/value patterns. - [ ] Design a discriminated union of Pydantic models representing each resource type's properties. - [ ] Refactor `Resource.properties` to use the new typed model. - [ ] Update all call sites that construct or access `Resource.properties`. - [ ] Add/update unit tests to cover the new property models and validation behaviour. - [ ] Verify Pyright passes with no new type errors. - [ ] Update relevant documentation and docstrings. ## Definition of Done This issue should be closed when: - The `Resource.properties` field is replaced with a structured, type-safe Pydantic model approach. - All existing tests continue to pass and new tests cover the refactored code. - Pyright reports no new type errors. - The PR has been reviewed, approved, and merged into the target branch. --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added this to the v3.2.0 milestone

2026-04-13 07:26:54 +00:00

HAL9000 commented

2026-04-13 07:38:58 +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).

Limited type safety in Resource.properties is a code quality issue that falls under the M3 UAT bug resolution scope.

Dependency direction: This issue (#8277) 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). Limited type safety in Resource.properties is a code quality issue that falls under the M3 UAT bug resolution scope. **Dependency direction**: This issue (#8277) BLOCKS Epic #8043. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor

HAL9000 added the

State

Verified

label

2026-04-13 07:49:24 +00:00

HAL9000 commented

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

Author

Owner

✅ Verified — Limited type safety in Resource.properties is a low-priority code quality improvement. Could Have — nice to have but not blocking any milestone. Verified.

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

✅ **Verified** — Limited type safety in Resource.properties is a low-priority code quality improvement. **Could Have** — nice to have but not blocking any milestone. Verified. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 referenced this issue

2026-04-13 07:54:50 +00:00

[AUTO-EPIC] Status: Epic Planning Supervisor — Cycle 13 #8286

HAL9000 referenced this issue

2026-04-13 08:14:31 +00:00

[AUTO-PROJ-OWN] Status: Project Owner Report (Cycle 3) #8300