From cf459e934af01a4751d0f6e5ecd07551b71dba79 Mon Sep 17 00:00:00 2001 From: bponders12-cell Date: Tue, 1 Sep 2026 21:05:47 -0400 Subject: [PATCH] Document stable identity migration and restore boundary --- MOTORSIGNAL_FINAL_CLOUD_DATA_MODEL.md | 32 +++++++++++++++++---------- 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/MOTORSIGNAL_FINAL_CLOUD_DATA_MODEL.md b/MOTORSIGNAL_FINAL_CLOUD_DATA_MODEL.md index 400b960..c4cc458 100644 --- a/MOTORSIGNAL_FINAL_CLOUD_DATA_MODEL.md +++ b/MOTORSIGNAL_FINAL_CLOUD_DATA_MODEL.md @@ -82,11 +82,13 @@ Telemetry samples and raw forensic records do not belong directly in the Firesto ## 4. Stable identity -The long-term canonical `rideId` must be an application-generated stable cloud identity, not a Firebase auto-ID and not a device-local database integer. +The long-term canonical `rideId` is an application-generated stable cloud identity, not a Firebase auto-ID and not a device-local database integer. -The current implementation uses `ride__` as a deterministic compatibility identity. This is safe for the current local database but is a migration target because a reinstall/new device can assign a different local integer ID. +The local `rides.cloudRideId` column was introduced in schema v6. New rides receive a random `ride_` identity once and retain it across sync retries, database restarts, and future restore operations. -Before multi-device restore is released, add a persisted stable ride cloud ID to the local ride model and migrate existing rides deterministically. All telemetry, metadata updates, retries, restore operations, and deletes must use that stable ID. +For pre-v6 local rides, the migration deliberately preserves compatibility with existing MotorCloud documents by assigning the exact legacy identity format `ride__`. Those IDs become persisted stable identities after migration, so existing cloud records remain addressable instead of being silently duplicated under new IDs. Newly created rides do not use local database IDs as their cloud identity. + +All telemetry, metadata updates, retries, restore operations, and deletes must use the persisted stable cloud ID. ## 5. Local-first lifecycle @@ -171,7 +173,7 @@ same stable rideId + same owner UID + repeated upload = one logical cloud ride ``` -Firestore writes use `set(..., merge: true)` against the deterministic ride document. R2 upload uses the deterministic object key and authenticated Worker validation. +Firestore writes use `set(..., merge: true)` against the stable ride document. R2 upload uses the stable object key and authenticated Worker validation. ## 9. Authentication rules @@ -270,7 +272,7 @@ Required invariants: ## 16. Multi-device restore contract -Restore should be additive and resumable: +Restore is additive and resumable: ```text Authenticate @@ -279,7 +281,7 @@ Read user metadata ↓ Discover cloud rides ↓ -Compare stable ride IDs +Compare persisted stable ride IDs ↓ Download missing metadata ↓ @@ -290,9 +292,11 @@ Materialize local records Mark local/cloud reconciliation complete ``` -Restore must never silently delete local rides. Conflicts must be surfaced or resolved using an explicit policy. +`CloudRestoreService` currently performs the metadata phase through `CloudReconciliationService`. It never deletes an existing local ride and never overwrites an existing local ride with cloud metadata merely because the cloud document differs. Divergent metadata is surfaced as a conflict for a future revision-aware policy. -## 17. Next implementation gates +The authenticated R2 download operation is intentionally a separate gate. No client code should pretend a telemetry bundle was restored until the Worker exposes a verified download contract. + +## 17. Implementation gates Before Free/Pro external testing: @@ -302,11 +306,15 @@ Before Free/Pro external testing: - [x] Back Up All UI and manager path - [x] Duplicate enqueue protection - [x] Explicit failed retry behavior -- [ ] Stable persisted cloud ride ID migration -- [ ] Automated Firebase Emulator ownership tests +- [x] Persisted stable cloud ride ID +- [x] v5 → v6 migration coverage +- [x] Fresh database coverage +- [x] Firebase Emulator ownership test suite +- [x] Additive cloud metadata reconciliation service +- [ ] R2 Worker authenticated download operation +- [ ] Telemetry bundle download/restore +- [ ] Revision-aware conflict resolution - [ ] Automated R2 Worker authorization tests -- [ ] Multi-device restore implementation -- [ ] Conflict/reconciliation implementation - [ ] Account deletion cascade - [ ] Account-level data export - [ ] Free/Pro cloud entitlement enforcement