# Individual driver suite — selected planning contract

Date: 2026-10-26. State: PLANNED / IMPLEMENTATION_NOT_STARTED_BY_THIS_PLAN.
Owner: [DRV-00–35 execution plan](docs-planning-DRIVER_SUITE_EXECUTION_PLAN.md).
User decision: the complete professional driver suite belongs to Premium.
This document authorizes no runtime, provider connection, sale, deployment or publication.

## Scope and amendment

Extend Abastevo for an individual app driver: Uber, 99, inDrive and user-defined channels are labels, not integrations or partnership claims. Reuse vehicle, refuel/charge/expense ledger, exact financial engines, metrics, cloud sync, subscriptions, owner proof, Room and map ports. Add private shifts, earnings, distance observations, cost profiles, maintenance, goals and reconciled reports. Preserve public/free exploration, community/trust, navigation and retained-data exit.

This selected planning amendment supersedes only the earlier exclusion of individual work earnings/operating results and voluntary work-session distance recording in PREMIUM_PRODUCT_CONTRACT and MOBILE_EXPANSION_CONTRACT for future DRV implementation. It does not alter financial-v1, EV measurement semantics or present runtime. Existing exclusions of fleets/employees, tenants, tax/payroll/invoicing, bank access, automatic movement detection and unauthorized third-party collection remain. No passenger identity or pickup/dropoff address is needed.

The driver suite is not an Uber-client replacement, ride marketplace, pricing instruction, tax product or profit guarantee. No app scraping, accessibility-based capture, notification/SMS reading, credentials to another platform, automatic ride acceptance or overlay over another app. Any official integration is a separate admitted adapter with approval/security/data-rights proof. Manual input and a bounded user-controlled import must independently complete the suite.

## Business rules

- **B-BR-DRV-01 — Premium and retained data:** new professional work/report generation follows verified existing capability and bounded offline lease; hosted mutations always recheck server authority. Do not infer entitlement from a client toggle. Preserve read/export/delete/correction of held local data on lapse. Do not create checkout, price, trial or provider activation. Free registration/social/trust/navigation are unchanged.
- **B-BR-DRV-02 — Exact units:** BRL integer centavos, quantity integer milli-L/milli-m3, energy Wh-compatible scale, distance integer metres, duration integer seconds. Localized km input/output converts exactly to/from metres. Preserve raw actual totals, method/version/source/timezone; checked sums, arbitrary-precision rational intermediates, one documented display rounding. Invalid/unknown never defaults to zero. Existing financial-v1 examples remain unchanged.
- **B-BR-DRV-03 — Historical safety:** existing odometer-unit ambiguity is not permission to multiply every row by 1000. Keep originals/revisions and inspect record provenance. Proven units migrate idempotently; ambiguous entries are flagged for owner review, remain exportable and cannot silently feed certified consumption. Preview, rollback/failure recovery and explicit repair receipts are required.
- **B-BR-DRV-04 — Earnings recognition:** distinguish work earned, received funds, platform-wallet movements and transfers. Support detailed gross/fees/tips/bonus/adjustments and net-only summaries with an explicit inclusive basis. Net-only does not imply known gross/fees. A payout of previously earned money is not new earnings. Reversals are typed signed adjustments with bounds, linkage and revision, not negative refuels.
- **B-BR-DRV-05 — Coverage and duplication:** detailed rides, shift/day/week summaries and imported rows carry platform/source-period/coverage metadata. Same source ID or exact retry converges; overlap across summary/detail/import requires reconciliation, not double counting. Tips/bonuses/reimbursements already included in a net summary are not added again. Preserve imported/raw meaning while excluding unnecessary passenger data.
- **B-BR-DRV-06 — Work session:** one active driver shift per owner across vehicles/origins under the declared local/hosted authority; concurrent-device offline starts can create a visible conflict, never pretend global uniqueness without a server. States READY/RUNNING/PAUSED/CLOSED/RECOVERY_REQUIRED/CONFLICT have explicit transitions. Pause time is distinct from work time. Platform online times can overlap; union time, not their sum, supplies a comparable total denominator.
- **B-BR-DRV-07 — Time truth:** active local duration uses monotonic time with a boot/session identity; persist UTC events and chosen IANA timezone for reporting. Wall-clock changes, reboot, force-stop or missing checkpoints create an explicitly bounded gap requiring review. Never invent time through a restart or silently auto-resume GPS. Corrected/backdated sessions invalidate reports.
- **B-BR-DRV-08 — Distance basis:** distinguish odometer readings, GPS estimate, user trip distance, app-reported paid distance and route prediction. Select one documented denominator per observation window; do not add GPS to odometer or count overlapping sessions twice. Paid/work-empty/personal partitions require explicit source/classification; GPS alone does not know whether a passenger is on board. Unknown distance prevents per-km results, not raw ledger entry.
- **B-BR-DRV-09 — Voluntary location:** manual mode works without permission. GPS distance requires a separate explicit start and visible stop, justified location/FGS behavior and current platform-policy review. Browsing/navigation does not consent to driver recording. Raw traces stay private/local, excluded from cloud/logs/training by default; store derived distance/quality/coverage only in allowed backup. Exporting a trace requires an explicit separate action. No automatic boot, worker or payment event starts collection.
- **B-BR-DRV-10 — Quality and lifecycle:** filter/reject invalid/stale/poor fixes and impossible jumps with a versioned reviewed policy; keep gap/quality reasons. Do not invent tunnel distance or promote route length into measured mileage. Coexist with MAP navigation through shared approved location ownership, explicit consumer leases and no duplicate totals. Stop releases one consumer without killing another legitimate session. Loss of permission/lapse/account/owner change stops GPS safely; existing local data remains.
- **B-BR-DRV-11 — Consumption:** reuse valid homogeneous-liquid full-to-full anchors and partial-fill accumulation, excluding the initial anchor. Preserve gap/reset/fuel/unit refusal. GNV purchases and measured odometer cost are allowed; unsupported gas-consumption methodology stays UNKNOWN, not fake km/L. EV distinguishes bought energy, measured battery energy and modeled reference; PHEV does not infer per-motor kilometres.
- **B-BR-DRV-12 — Views of money:** show (a) receipts/disbursements on a declared cash-account basis, (b) earned net work value and recorded operating result for a complete matched window, and (c) separately labeled modeled economic result. A bank payout/wallet transfer is not duplicated as earnings. Fuel bought today does not prove fuel consumed on today's shift. Missing matching/mandatory costs yields a partial result or UNKNOWN with coverage.
- **B-BR-DRV-13 — Cost attribution:** existing expense/refuel/charge records remain authoritative. Allocate across work/personal, vehicle, time and distance only through a versioned explicit basis. Totals of allocations never exceed the source amount; deterministic centavo residual rule preserves sums. Do not create duplicate ledger expenses through a shift link. Costs outside the chosen window are not silently included.
- **B-BR-DRV-14 — Estimated costs:** owner-entered maintenance reserve, depreciation and recurring costs are scenarios, not cash payments. Keep model and actual views separate; replacing a reserve with a realized expense follows an explicit reconciliation rule, never subtracts both. Loan principal is a cash/capital flow, interest/fees may be a separate recorded cost, and lease cost is distinct from depreciation of an owned vehicle. Unknown assumptions stay visible.
- **B-BR-DRV-15 — Ratios:** income/km, recorded result/km and result/hour identify the numerator, eligible distance/time, window and coverage. Weighted comparison divides compatible sums, never averages per-ride ratios or mixes methods. Profitability never follows from a fuel-price lookup or partial-month denominator. Fixed-cost break-even requires positive known contribution margin; otherwise show not computable/unattainable under the scenario.
- **B-BR-DRV-16 — Maintenance and goals:** manual km/time/service-based reminders, configurable goals and bounded local alerts are advisory. Corrected odometer/segment resets recompute them. Goal progress uses the chosen recorded/modeled view. A parked manual trip scenario uses offered value, pickup/paid/empty-return distance, duration and declared fees/cost profile; no app scraping or automatic acceptance. Ride counts and average ticket require nonoverlapping source coverage; absent counts stay unknown. Do not claim predicted earnings or financial advice. No commission percentage, tariff, depreciation rate or tax is invented by defaults.
- **B-BR-DRV-17 — Offline and authority:** durable owner/origin-scoped transaction precedes success; stable operation ID/body digest/expected revision/deletion epoch and server receipts enforce replay. Negative auth/IDOR/concurrency tests are immediate. Outbox is bounded, visible and recoverable with no silent loss. Cloud opt-in and live capability are independent of local retention.
- **B-BR-DRV-18 — Restore/erasure:** every new dataset registers export, backup, erasure and stale-restore/tombstone behavior. Snapshots include acknowledged allowed records, no private keys/tokens/raw GPS. Preview guest adoption and owner conflicts; a second account never gets the first account's shifts. Free data exit survives lapse and deletion epochs are applied before restored data can be served.
- **B-BR-DRV-19 — Inputs and reports:** user-controlled standardized CSV first; platform-specific templates only after actual reviewed samples, permission and semantic mapping. Bound bytes/rows/cells/archives and handle encoding/decimal/timezone/import revision. Preview and transactional commit/retry with duplicate/overlap checks. CSV export protects formula injection; PDF/Android print is local if admitted, with safe sharing. No fictitious provider receipt is evidence.
- **B-BR-DRV-20 — Driving safety and UX:** setup/edit/reconcile happens while parked. Active UI emphasizes large start/pause/stop controls and minimal status, with TalkBack/text scaling/dark mode and honest pending/error/offline states. Voice, if optional, uses admitted local TTS without speaking earnings on a lockscreen by default. The suite fits existing navigation without replacing the four-tab map shell.
- **B-BR-DRV-21 — Evidence:** source implementation, local acceptance, protected integration, staging proof, owned-device field proof and commercial/production certification are distinct. No missing provider approval, physical battery run or participant study becomes PASS because the source compiles or a plan exists.

## Use cases

1. **BUC-DRV-01:** configure owned/rented/financed vehicle, energy/fuel and optional cost assumptions; preserve existing IDs/history.
2. **BUC-DRV-02:** start/pause/end a manual shift with odometer and breaks; recover an interrupted shift through explicit review.
3. **BUC-DRV-03:** opt into GPS distance for that session, inspect coverage and stop; continue manually after permission loss.
4. **BUC-DRV-04:** register/correct refuel, charge, expense and gap/segment without publishing a community observation.
5. **BUC-DRV-05:** enter detailed earnings or a platform summary, cash receipt or payout; reconcile overlaps and included components.
6. **BUC-DRV-06:** view matched-window km/L, actual paid totals, cost/km, earnings/km/hour and recorded versus modeled result with unknowns.
7. **BUC-DRV-07:** set goals and maintenance reminders; inspect scenarios without a profit or safety guarantee.
8. **BUC-DRV-08:** import a local reviewed statement, preview/match/deduplicate/commit and export an owner report.
9. **BUC-DRV-09:** sync/restore two own installations; resolve edits and preserve erasure, retained reads and logout isolation.
10. **BUC-DRV-10:** inspect day/week/month/custom reports by vehicle/platform/method with revision and source coverage.

## Architecture and ownership

Pure rules stay in existing Kotlin domain and Go metrics where authoritative shared computation is needed. Extend ledger and metrics through their existing ports; do not fork refuel/expense histories into a second ledger. A proposed `driver` backend boundary owns shifts/earnings/distance/cost-profile/maintenance/import identities and accesses ledger/vehicle/subscription via explicit ports, not cross-module SQL. Confirm module naming and needed migrations in DRV-00/06; these are proposed targets, not existing commands. PostgreSQL/PostGIS, pgx/sqlc/chi, Room, Hilt and WorkManager remain the established stack. No new database, payment processor, telemetry service, GPS SDK, tax engine or hosted BI service is required.

New OpenAPI/schema/dataset names and quotas are frozen before implementation against the current repository; do not copy invented live routes from this planning document. Model private normal-form data and report snapshots with revisions/fingerprints, not an unbounded event-sourcing rewrite. A car-service exception must document privacy/permission/lifecycle ownership rather than broadly weakening guards against hidden GPS.

## Decisions to freeze at DRV-00

Confirmed by the owner: the professional suite is Premium. Selected plan design for DRV-00 review: Android first, individual driver, manual offline input, optional explicitly initiated GPS, BRL-first and no live platform dependency. Proposed for acceptance before behavior: entry labels, report timezone defaults, offline lease reuse, limits from existing bounds and measured workloads, trace-retention policy (off by default), negative-adjustment taxonomy, centavo allocation residual, recurring-cost proration and one-active-shift conflict resolution. Do not wait for store/provider credentials to build pure/local contracts; do not certify hosted paid behavior without its actual proof.

## Primary external references, checked 2026-10-26

- [Uber Driver API scopes](https://developer.uber.com/docs/drivers/guides/scopes): access is limited; an official connector remains gated by actual access/scopes and a reviewed data contract.
- [Android foreground-service start restrictions](https://developer.android.com/develop/background-work/services/fgs/restrictions-bg-start): review actual target/runtime behavior before location implementation.
- [Google Play background-location policy](https://support.google.com/googleplay/android-developer/answer/9799150): a foreground service alone is not proof that store-policy review is unnecessary.
- [ANPD security guide materials](https://www.gov.br/anpd/pt-br/centrais-de-conteudo/materiais-educativos-e-publicacoes/guia-orientativo-sobre-seguranca-da-informacao-para-agentes-de-tratamento-de-pequeno-porte): use these as input to the data inventory/security review; a checklist is not legal compliance certification.