GIA/artifacts/plans/03-media-asset-normalization.md

Feature Plan: Media Asset Normalization

Goal

Normalize media into reusable assets so messages reference media IDs rather than duplicate transport blobs.

Why This Fits GIA

• GIA already has shared media prep and cross-transport relay.
• Normalized assets reduce duplicate downloads/uploads and improve traceability.

Scope

• New MediaAsset entity with checksum + metadata.
• New link table between Message and MediaAsset.
• De-dup by sha256 and file size.

Implementation

1. Add models/migrations: MediaAsset, MessageMediaRef.
2. Update inbound media ingestion to upsert MediaAsset.
3. Update outbound transport prep to consume MediaAsset references.
4. Add background backfill for existing attachments.
5. Add retention/GC strategy for orphaned assets.

Acceptance Criteria

• Same file across transports resolves to one MediaAsset.
• Message records keep only pointers and display metadata.
• Relay path can reuse existing asset without re-download.

Out of Scope

• External CDN migration in this phase.