chore: cleanup of history file

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

@@ -0,0 +1,57 @@
+# 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