docs product DRV_13_CONTRACT

DRV-13 — Owner-scoped Android state and migrations contract

Date: 2026-10-26. B-BR-DRV-02/06/07/09/10/17. Freeze before behavior.

Scope

This phase adds the Room foundation for driver records before the UI/sync phases. It does not add a driver screen, GPS collector, WorkManager recorder, network sync or cloud consent. Existing ledger, map, vehicle and session tables are unchanged.

Schema and ownership

• Room schema 29 adds driver_shift, driver_shift_gap, driver_earning, driver_earning_revision, driver_distance, driver_local_command and driver_draft. Every primary key starts with owner_account + origin; every DAO read filters both. There is no unscoped driver query.
• Integer units stay integer: distance metres, money centavos, duration seconds. NULL remains unknown; zero remains a known zero. No localized string is the storage source of truth.
• No driver table or draft contains latitude, longitude, a raw trace, a GPS active flag or an automatic-start marker. Rehydration cannot start location.
• Drafts store a JSON body plus exact metre/centavo/second fields and a unit version. Reopening after process death returns the same integer values.

Atomic local writes

• Earning save writes the current fact, an immutable revision and the first local command in one Room transaction. A duplicate revision aborts and rolls back the entire save.
• Shift save replaces the shift and its gaps atomically; distance save writes the observation and command atomically.
• Owner/origin switches, guest (owner="") and process restart cannot read another partition. No silent migration of drafts between owners.

Migration and repair

• Migration 28→29 is append-only: it creates the seven driver tables/indexes and does not drop, alter or delete ledger, map, vehicle or session rows.
• A fresh install opens schema 29; a supported 28→29 upgrade preserves seeded ledger draft, vehicle and saved-place rows. Close/reopen preserves driver drafts.
• Legacy ambiguous odometer repair remains the existing DRV-02/05 ledger-draft flow (explicit preview + CAS/receipt, idempotent retry). This phase does not duplicate or auto-apply that repair.

Evidence boundary

Room schema JSON 29, JVM migration checks and an owned Android emulator migration

• persistence test are required. UI/Compose, GPS, cloud sync, API26 and production acceptance remain later gates. A compile-only result is not enough.