markitect-main/history/2025/251025-migration-reports/ASSET_MODEL_MIGRATION.md

Asset Model Migration Plan

Goal

Convert from dict-based asset representation to object-based Asset model for better type safety and test compatibility.

Current State

• AssetRegistry.list_assets() returns List[Dict[str, Any]]
• Tests expect List[Asset] with attributes like asset.filename
• Multiple inconsistent field names: content_hash vs hash, size_bytes vs size

Migration Strategy

Phase 1: Add Model Support (Non-Breaking)

1. ✅ Create Asset dataclass with from_dict() and to_dict() methods
2. Add AssetRegistry.list_assets_as_objects() method
3. Update tests to use new method

Phase 2: Gradual Migration

1. Update AssetManager to return Asset objects
2. Update CLI commands to use object interface
3. Update analytics and discovery modules

Phase 3: Storage Migration

1. Update registry storage format (optional - can keep dict storage)
2. Remove old methods
3. Update all remaining code

Implementation Steps

1. Update AssetRegistry

def list_assets_as_objects(self) -> List[Asset]:
    """List all assets as Asset objects."""
    asset_dicts = self.list_assets()
    return [Asset.from_dict(asset_dict) for asset_dict in asset_dicts]

2. Update AssetManager

def list_assets(self) -> List[Asset]:
    """List all assets with enhanced information."""
    return self.registry.list_assets_as_objects()

3. Update Tests

• Change [asset.filename for asset in assets] to work with objects
• Update assertions to use object attributes

Benefits After Migration

• ✅ Type safety and IDE support
• ✅ Test compatibility
• ✅ Cleaner, more maintainable code
• ✅ Future extensibility (methods, computed properties)

Risks

• Temporary complexity during migration
• Need to ensure backward compatibility during transition