UAT: Virtual resource equivalence tracking service not implemented — virtual resource types defined but no service auto-links physical resources to virtual parents #3599

Open
opened 2026-04-05 20:16:42 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: fix/virtual-resource-equivalence-tracking-service
  • Commit Message: feat(resources): implement virtual resource equivalence tracking service
  • Milestone: v3.6.0
  • Parent Epic: #366

Background

Per docs/specification.md (Virtual Resources section), virtual resources are an abstraction representing equivalence identity for physical resources that share the same content. The spec states:

Virtual Resources: An abstraction representing an equivalence identity for physical resources that share the same content. They have no physical location and cannot be directly read or written.

The codebase defines 9 built-in virtual resource types with equivalence criteria:

  • file (criteria: content_hash, filename, permissions)
  • directory (criteria: merkle_hash, name, permissions)
  • commit (criteria: commit_hash)
  • branch (criteria: name, head_commit_hash)
  • tag (criteria: name, target_sha)
  • tree (criteria: tree_hash)
  • remote (criteria: url)
  • submodule (criteria: url, path)
  • symlink (criteria: name, target_path)

Each virtual type has an equivalence configuration with criteria fields that define when two physical resources should be considered equivalent and linked to the same virtual parent.

Current Behavior

The Resource domain model (src/cleveragents/domain/models/core/resource.py) has a content_hash field for equivalence tracking, but there is no service that uses this field to auto-link physical resources to virtual parents.

Searching the codebase reveals:

  • _resource_registry_virtual.py — defines virtual types with equivalence criteria (data only)
  • _resource_registry_virtual_deferred.py — defines more virtual types (data only)
  • resource/schema.py — validates that virtual types have equivalence config
  • infrastructure/database/models.pyequivalence_json column exists on resource_types table

Missing: There is no EquivalenceTrackingService or equivalent that:

  1. Computes equivalence criteria values for a physical resource
  2. Searches for existing virtual resources matching those criteria
  3. Creates a new virtual resource if none exists
  4. Links the physical resource as a child of the virtual resource

The ResourceRepository.auto_discover_children() method exists but only handles auto-discovery of child resources, not virtual parent linking.

Expected Behavior

Per the specification, when a physical resource is registered (e.g., an fs-file), the system should:

  1. Compute its equivalence criteria (e.g., content_hash, filename, permissions)
  2. Search for an existing file virtual resource with matching criteria
  3. If found: link the physical resource as a child of the existing virtual resource
  4. If not found: create a new file virtual resource and link the physical resource as its child

This enables the cross-layer identity model described in the spec: two fs-file resources with the same content hash, filename, and permissions are automatically linked to the same file virtual parent.

Code Locations

  • src/cleveragents/application/services/_resource_registry_virtual.py — virtual type definitions with equivalence criteria (no service logic)
  • src/cleveragents/domain/models/core/resource.pycontent_hash field exists but unused for equivalence
  • src/cleveragents/infrastructure/database/repositories.pyResourceRepository has no equivalence tracking methods
  • src/cleveragents/application/services/ — no EquivalenceTrackingService or similar

Impact

Without equivalence tracking, virtual resource types are purely decorative — they exist in the registry but no physical resources are ever linked to them. The cross-layer identity model (a core M7 feature) is completely non-functional.

Subtasks

  • Design EquivalenceTrackingService interface per spec
  • Implement compute_equivalence_key() — extracts criteria values from a resource's properties dict based on its virtual type's equivalence.criteria
  • Implement find_or_create_virtual_parent() — searches for matching virtual resource, creates if absent
  • Implement link_physical_to_virtual() — adds physical resource as child of virtual parent
  • Integrate into ResourceRegistryService.register_resource() — call equivalence tracking after registration
  • Write Behave unit tests covering: new physical resource creates virtual parent, second physical resource with same criteria links to existing virtual parent, different criteria creates separate virtual parent
  • Write Robot Framework integration test verifying end-to-end equivalence linking
  • Verify all nox stages pass; coverage ≥ 97%

Definition of Done

  • EquivalenceTrackingService (or equivalent) implemented
  • Physical resources are automatically linked to virtual parents on registration
  • Two physical resources with matching equivalence criteria share the same virtual parent
  • Unit and integration tests pass
  • All nox stages pass; coverage ≥ 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/virtual-resource-equivalence-tracking-service` - **Commit Message**: `feat(resources): implement virtual resource equivalence tracking service` - **Milestone**: v3.6.0 - **Parent Epic**: #366 ## Background Per `docs/specification.md` (Virtual Resources section), virtual resources are an abstraction representing equivalence identity for physical resources that share the same content. The spec states: > **Virtual Resources**: An abstraction representing an equivalence identity for physical resources that share the same content. They have no physical location and cannot be directly read or written. The codebase defines 9 built-in virtual resource types with equivalence criteria: - `file` (criteria: `content_hash`, `filename`, `permissions`) - `directory` (criteria: `merkle_hash`, `name`, `permissions`) - `commit` (criteria: `commit_hash`) - `branch` (criteria: `name`, `head_commit_hash`) - `tag` (criteria: `name`, `target_sha`) - `tree` (criteria: `tree_hash`) - `remote` (criteria: `url`) - `submodule` (criteria: `url`, `path`) - `symlink` (criteria: `name`, `target_path`) Each virtual type has an `equivalence` configuration with `criteria` fields that define when two physical resources should be considered equivalent and linked to the same virtual parent. ## Current Behavior The `Resource` domain model (`src/cleveragents/domain/models/core/resource.py`) has a `content_hash` field for equivalence tracking, but there is **no service that uses this field to auto-link physical resources to virtual parents**. Searching the codebase reveals: - `_resource_registry_virtual.py` — defines virtual types with equivalence criteria (data only) - `_resource_registry_virtual_deferred.py` — defines more virtual types (data only) - `resource/schema.py` — validates that virtual types have equivalence config - `infrastructure/database/models.py` — `equivalence_json` column exists on `resource_types` table **Missing**: There is no `EquivalenceTrackingService` or equivalent that: 1. Computes equivalence criteria values for a physical resource 2. Searches for existing virtual resources matching those criteria 3. Creates a new virtual resource if none exists 4. Links the physical resource as a child of the virtual resource The `ResourceRepository.auto_discover_children()` method exists but only handles auto-discovery of child resources, not virtual parent linking. ## Expected Behavior Per the specification, when a physical resource is registered (e.g., an `fs-file`), the system should: 1. Compute its equivalence criteria (e.g., `content_hash`, `filename`, `permissions`) 2. Search for an existing `file` virtual resource with matching criteria 3. If found: link the physical resource as a child of the existing virtual resource 4. If not found: create a new `file` virtual resource and link the physical resource as its child This enables the cross-layer identity model described in the spec: two `fs-file` resources with the same content hash, filename, and permissions are automatically linked to the same `file` virtual parent. ## Code Locations - `src/cleveragents/application/services/_resource_registry_virtual.py` — virtual type definitions with equivalence criteria (no service logic) - `src/cleveragents/domain/models/core/resource.py` — `content_hash` field exists but unused for equivalence - `src/cleveragents/infrastructure/database/repositories.py` — `ResourceRepository` has no equivalence tracking methods - `src/cleveragents/application/services/` — no `EquivalenceTrackingService` or similar ## Impact Without equivalence tracking, virtual resource types are purely decorative — they exist in the registry but no physical resources are ever linked to them. The cross-layer identity model (a core M7 feature) is completely non-functional. ## Subtasks - [ ] Design `EquivalenceTrackingService` interface per spec - [ ] Implement `compute_equivalence_key()` — extracts criteria values from a resource's `properties` dict based on its virtual type's `equivalence.criteria` - [ ] Implement `find_or_create_virtual_parent()` — searches for matching virtual resource, creates if absent - [ ] Implement `link_physical_to_virtual()` — adds physical resource as child of virtual parent - [ ] Integrate into `ResourceRegistryService.register_resource()` — call equivalence tracking after registration - [ ] Write Behave unit tests covering: new physical resource creates virtual parent, second physical resource with same criteria links to existing virtual parent, different criteria creates separate virtual parent - [ ] Write Robot Framework integration test verifying end-to-end equivalence linking - [ ] Verify all nox stages pass; coverage ≥ 97% ## Definition of Done - [ ] `EquivalenceTrackingService` (or equivalent) implemented - [ ] Physical resources are automatically linked to virtual parents on registration - [ ] Two physical resources with matching equivalence criteria share the same virtual parent - [ ] Unit and integration tests pass - [ ] All nox stages pass; coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.6.0 milestone 2026-04-05 20:16:47 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Critical — Virtual resource equivalence tracking service is not implemented. Virtual resource types are defined in the spec but the tracking service is missing.
  • Milestone: v3.6.0 (already assigned)
  • Story Points: 8 — XL — Requires implementing a new service from scratch for virtual resource equivalence tracking.
  • MoSCoW: Should Have — Virtual resources are an advanced feature defined in the spec. While important for completeness, the core resource types (physical, cloud, database) work. Virtual resource equivalence is needed for advanced use cases but not for basic milestone demos.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — Virtual resource equivalence tracking service is not implemented. Virtual resource types are defined in the spec but the tracking service is missing. - **Milestone**: v3.6.0 (already assigned) - **Story Points**: 8 — XL — Requires implementing a new service from scratch for virtual resource equivalence tracking. - **MoSCoW**: Should Have — Virtual resources are an advanced feature defined in the spec. While important for completeness, the core resource types (physical, cloud, database) work. Virtual resource equivalence is needed for advanced use cases but not for basic milestone demos. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
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
#366 Epic: Post-MVP Deferred Work
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3599
No description provided.