markitect-main/history/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
```python
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
```python
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