feat: Complete versioning system transformation

docs/versioning/MIGRATION.md

@@ -33,8 +33,64 @@ The new system uses dedicated relational tables:
 
 - ✅ All new versions written to relational tables
 - ✅ Triggers active on all entity tables
+- ✅ Automated cleanup scheduled via pg_cron
 - ⚠️ Old `entity_versions` table retained for backward compatibility
-- ⚠️ `src/lib/versioningHelpers.ts` deprecated but not removed
+- ⚠️ `src/lib/versioningHelpers.ts` deprecated but not removed (scheduled for removal: 2025-12-01)
+
+## Migration Timeline
+
+### ✅ Phase 1: New System Deployed (Completed)
+- Relational version tables created (`park_versions`, `ride_versions`, etc.)
+- Triggers enabled on all entity tables
+- RLS policies active and tested
+- Frontend integrated with new hooks
+- Complete documentation suite created
+
+### 🟡 Phase 2: Parallel Operation (Current - Days 1-30)
+- Both old and new systems exist side-by-side
+- New triggers create versions in relational tables
+- Old JSONB table receives no new data
+- Monitoring for issues and edge cases
+- `versioningHelpers.ts` marked as deprecated
+
+**Action Items:**
+- [ ] Monitor version creation in new tables
+- [ ] Verify no new inserts to old `entity_versions` table
+- [ ] Search codebase for deprecated function usage
+- [ ] Collect feedback from team
+
+### 🔵 Phase 3: Archive Legacy Data (Day 30)
+- Archive old `entity_versions` to `entity_versions_archive`
+- Verify data integrity and counts match
+- Keep archive for 60 more days as safety net
+- Document archive location and access procedures
+
+**SQL Migration:**
+```sql
+-- See supabase/migrations/*_archive_legacy_versions.sql
+CREATE TABLE entity_versions_archive (LIKE entity_versions INCLUDING ALL);
+INSERT INTO entity_versions_archive SELECT * FROM entity_versions;
+```
+
+### 🟢 Phase 4: Drop Legacy Tables (Day 90)
+- Drop old `entity_versions` table
+- Drop old RPC functions (`create_entity_version`, `compare_versions`, etc.)
+- Remove `src/lib/versioningHelpers.ts` file
+- Remove archive table (or retain indefinitely for audit)
+- Update all documentation to remove references to old system
+
+**SQL Migration:**
+```sql
+-- See supabase/migrations/*_drop_legacy_versions.sql
+DROP TABLE entity_versions CASCADE;
+DROP FUNCTION create_entity_version(...);
+```
+
+### 🚀 Phase 5: Optimization (Ongoing)
+- Automated cleanup via pg_cron (monthly)
+- Performance monitoring and index tuning
+- Documentation updates based on usage patterns
+- Version retention policy adjustments as needed
 
 ## Backfill Script (Optional)