docs product DRV_11_CONTRACT

DRV-11 — Revisioned reports and private HTTP contract

Date: 2026-10-26. B-BR-DRV-12/15/17; BUC-DRV-06/09/10. Freeze before behavior.

Scope

This phase exposes private driver earnings pages and revisioned reports over HTTP, backed by owner-scoped storage. It does not add a mobile UI, cloud opt-in, provider integration, checkout or public endpoint. The feature is off unless ANPFUEL_DRIVER_ENABLED=true; disabled routes return 404 without touching storage and the existing ledger/app routes are unchanged.

Report projection

• Windows: DAY, WEEK (Monday start), MONTH and CUSTOM in an explicit IANA timezone. The window is half-open [from, to); CUSTOM is bounded to 366 days.
• Earnings are owner/vehicle scoped, optionally platform-filtered, and must be fully contained in the window. Partial overlap is explicit coverage, never a silent clipped sum. Current adjustments are included only when their target revision is current; stale/obsolete adjustments leave the result unknown.
• Costs use the newest cost-profile version effective at the window start. Only items whose effective period is fully inside the window are included; partial/open-ended items or unknown amounts make coverage incomplete and the recorded result unknown. Actual and modeled costs stay separate. No fuel purchase is treated as consumed fuel and no rate/tax/depreciation is invented.
• Distance selects exactly one documented basis/window observation. GPS and odometer are never added. Unknown distance prevents per-km results.
• Work time is not projected in this phase (shift wall-clock start/end are not persisted); time ratios are explicitly unavailable, never zero.
• Money is integer BRL centavos, distance integer metres; ratios use exact rational intermediates and are returned as strings. Generated reports carry a SHA256 source revision computed from earnings revisions, adjustments, cost profile and distance content.
• Source reads are bounded to 1000 rows. More rows fail with driver: report source exceeds bounded limit; lists are never silently truncated. An expected revision that no longer matches fails with driver: stale report revision before writing a snapshot.

Snapshots and HTTP

• driver_report_snapshots stores owner/vehicle/window/timezone/platform/basis, source revision, increasing snapshot version, private JSON payload and generation time. Account soft/physical deletion erases it. A worker cleanup removes snapshots older than 400 days in bounded batches (1000/run).
• POST /v1/driver/reports/build requires live account session, exact-body signed owner key and professional.report; it recomputes and upserts.
• POST /v1/driver/reports/get is a free retained read; it returns no-store data only when the stored source revision still matches, otherwise 409 stale.
• POST /v1/driver/earnings is a free retained read with 1..100 items, owner-bound HMAC cursor, no-store and no ETag.
• All routes require signed owner proof. Errors are no-store and do not leak owner data. Cursors are bound to owner/origin; cross-owner use fails.

Evidence boundary

Real disposable PostGIS must prove window/revision recomputation after late edits, stale snapshot refusal, cost/distance coverage, retained reads after capability lapse, snapshot erasure, bounded cleanup, HTTP no-store/cursor/auth and feature-disabled 404. OpenAPI golden vectors preserve exact units. Real provider identity/payment proof, mobile/device acceptance and production certification remain later gates.