# Models.py Refactoring Summary

## Overview
Refactored `models.py` PipeObject class to align with the hash+store canonical pattern, removing all backwards compatibility and legacy code.

## PipeObject Changes

### Removed Legacy Fields
- ❌ `source` - Replaced with `store` (storage backend name)
- ❌ `identifier` - Replaced with `hash` (SHA-256 hash)
- ❌ `file_hash` - Replaced with `hash` (canonical field)
- ❌ `remote_metadata` - Removed (can go in metadata dict or extra)
- ❌ `mpv_metadata` - Removed (can go in metadata dict or extra)
- ❌ `king_hash` - Moved to relationships dict
- ❌ `alt_hashes` - Moved to relationships dict
- ❌ `related_hashes` - Moved to relationships dict
- ❌ `parent_id` - Renamed to `parent_hash` for consistency

### New Canonical Fields
```python
@dataclass(slots=True)
class PipeObject:
    hash: str              # SHA-256 hash (canonical identifier)
    store: str             # Storage backend name (e.g., 'default', 'hydrus', 'test')
    tags: List[str]
    title: Optional[str]
    source_url: Optional[str]
    duration: Optional[float]
    metadata: Dict[str, Any]
    warnings: List[str]
    file_path: Optional[str]
    relationships: Dict[str, Any]  # Contains king/alt/related
    is_temp: bool
    action: Optional[str]
    parent_hash: Optional[str]     # Renamed from parent_id
    extra: Dict[str, Any]
```

### Updated Methods

#### Removed
- ❌ `register_as_king(file_hash)` - Replaced with `add_relationship()`
- ❌ `add_alternate(alt_hash)` - Replaced with `add_relationship()`
- ❌ `add_related(related_hash)` - Replaced with `add_relationship()`
- ❌ `@property hash` - Now a direct field
- ❌ `as_dict()` - Removed backwards compatibility alias
- ❌ `to_serializable()` - Removed backwards compatibility alias

#### Added/Updated
- ✅ `add_relationship(rel_type, rel_hash)` - Generic relationship management
- ✅ `get_relationships()` - Returns copy of relationships dict
- ✅ `to_dict()` - Updated to serialize new fields

## Updated Files

### cmdlets/_shared.py
- Updated `coerce_to_pipe_object()` to use hash+store pattern
- Now computes hash from file_path if not provided
- Extracts relationships dict instead of individual king/alt/related fields
- Removes all references to source/identifier/file_hash

### cmdlets/add_file.py
- Updated `_update_pipe_object_destination()` signature to use hash/store
- Updated `_resolve_source()` to use pipe_obj.hash
- Updated `_prepare_metadata()` to use pipe_obj.hash
- Updated `_resolve_file_hash()` to check pipe_obj.hash
- Updated all call sites to pass hash/store instead of source/identifier/file_hash

### cmdlets/add_tag.py & cmdlets/add_tags.py
- Updated to access `res.hash` instead of `res.file_hash`
- Updated dict access to use `get('hash')` instead of `get('file_hash')`

### cmdlets/trim_file.py
- Updated to access `item.hash` instead of `item.file_hash`
- Updated dict access to use `get('hash')` only

### metadata.py
- Updated IMDb, MusicBrainz, and OpenLibrary tag extraction to return dicts directly
- Removed PipeObject instantiation with old signature (source/identifier)
- Updated remote metadata function to return dict instead of using PipeObject

## Benefits

1. **Canonical Pattern**: All file operations now use hash+store as the single source of truth
2. **Simplified Model**: Removed 9 legacy fields, consolidated into 2 canonical fields + relationships dict
3. **Consistency**: All cmdlets now use the same hash+store pattern for identification
4. **Maintainability**: One code path, no backwards compatibility burden
5. **Type Safety**: Direct fields instead of computed properties
6. **Flexibility**: Relationships dict allows for extensible relationship types

## Migration Notes

### Old Code
```python
pipe_obj = PipeObject(
    source="hydrus",
    identifier=file_hash,
    file_hash=file_hash,
    king_hash=king,
    alt_hashes=[alt1, alt2]
)
```

### New Code
```python
pipe_obj = PipeObject(
    hash=file_hash,
    store="hydrus",
    relationships={
        "king": king,
        "alt": [alt1, alt2]
    }
)
```

### Accessing Fields
| Old | New |
|-----|-----|
| `obj.file_hash` | `obj.hash` |
| `obj.source` | `obj.store` |
| `obj.identifier` | `obj.hash` |
| `obj.king_hash` | `obj.relationships.get("king")` |
| `obj.alt_hashes` | `obj.relationships.get("alt", [])` |
| `obj.parent_id` | `obj.parent_hash` |

## Zero Backwards Compatibility
As requested, **all backwards compatibility has been removed**. Old code using the previous PipeObject signature will need to be updated to use hash+store.