# Premium private cloud protocol v1

PRM02 opening; rules B-BR-PR06–PR12 and BUC-PR02/07. One account owns each record; local UUIDs remain unchanged and are scoped by owner (the same UUID in a different account never selects the first account's data). No tenant/fleet ownership.

Vehicles are typed version-1 records: local UUID, display name (1–100 Unicode characters, no controls), tank capacity in integer milli-units (positive, <=200000, multiples of 10 to preserve local two-decimal precision), canonical fuel/unit pair, existing cheapest/specific-CNPJ source, basic-alert switch, nonnegative sort order and archived flag. Legacy GASOLINE_PREMIUM maps explicitly to GASOLINE_ADDITIVED; true premium grade stays distinct. LPG_P13 is not a vehicle tank fuel; unsupported local records remain local and produce a recoverable import error. Archived vehicles count toward the existing three-record ceiling. Import never changes local IDs or allocates a fourth hosted vehicle.

Private commands resolve owner via session and require current signed contributor/key binding. Store locks owner/session/key before live capability check in the same transaction. Missing paid port fails closed. No deployable synthetic entitlement. Initial identical vehicle import converges; divergent existing UUID requires expected revision and explicit resolution. No automatic guest upload or account merge is implied. Consent, device proofs, common receipts and public owner APIs land in their owning tasks before any consumer is enabled.

PRM02-T02 allowlist: favorite key equals canonical station UUID; only currently active directory references can be newly selected. Missing/retired references are not recreated, and later reads can report unavailable. No backend following/favorite subscription implementation was found in this main-based source; this private set does not create free push/follow subscriptions. Maximum 1000 hosted favorites (source ceiling, not capacity evidence), one portable preferences singleton.

Portable preference v1 fields only: chosen state/municipality, exact fuel, supported locale and user-selected flag, show-price-history, nearest-search radius. Supported locale tags mirror AppLocales (pt-BR/en/es/fr/zh-CN/ru/de/ja or empty system default). State must be a Brazilian UF; municipality is an optional seven-digit IBGE code and requires a UF. All local sync/Wi-Fi/battery/permission/onboarding/auth/signing/purchase/location/photo/cache fields are excluded. Unknown fields and versions refuse; no generic JSON preference replication. Free local preferences/favorites are unchanged.

PRM02-T03 device references: server-generated random UUID, bound to owner + current session family + signing contributor/key + trusted server origin. They contain no hardware/ad identifier or independent bearer credential. Current signed account proof is required every command/pull; a device UUID alone grants nothing. At most three unrevoked device references per account across origins; a revoked/expired session cannot use its reference. Revocation is a free signed owner operation, preserves cloud/local records, and cannot be undone by restoring old device rows. Re-register with fresh proof to mint a new reference; old UUID remains revoked. Successful command transactions alone update last-success. Account deletion immediately revokes all references.

PRM02-T04 commands: at most 50 operations / 64 KiB canonical batch / 8 KiB per record, 600 new commands/hour and 10000 retained receipts/account; receipts retain 30 days, never silently evict within that window. Each UUID operation binds dataset, resource UUID, expected record revision, deletion flag, normalized payload, owner epoch and consent revision. Identical committed replay returns its original operation result; changed reuse conflicts. Owner-global revisions order changes; record revisions guard conditional writes. One SQL transaction owns the full batch and durable receipts; failure rolls everything back. Current device and paid capability are checked inside the transaction and again before commit; exact replay does not recover revoked authority.

Consent mask defaults OFF. The command envelope includes the current consent revision and refuses a disabled dataset; the opt-in/import user flow is PRM03-T03. No API caller can directly set a mask or epoch. Account deletion bumps the durable epoch and clears payloads/devices/changes. Record deletion nulls previous change payloads and writes an opaque erased-ID fence before removing content; old edits/UUID recreation cannot resurrect it. Receipts contain only operation/resource/result metadata, never retained old payload/name/credentials. Restored infrastructure must replay the separate external erasure ledger before serving; local epoch tables alone do not certify that operational recovery.

Vehicle removal uses the archived flag until the professional dependency/cascade-preview port exists; command hard-delete of a vehicle is refused. Free personal-data erasure is a distinct owner operation and does not imply business cascade semantics.

PRM02-T05 APIs: current account-session proof resolves owner; signed proof additionally protects device registration/revocation, commands and free erasure. Owner status, dataset pages, device pages and explicit cloud export/inventory are free; they never accept an account ID or restore credentials. Record pages are 20 by default / 100 maximum with authenticated owner/origin/dataset/epoch/schema-bound 15-minute cursors; responses are no-store without ETags. Export scope is the registered cloud datasets, not the existing contributor-only public-participation archive. Future professional/rule/snapshot datasets must register their own inventory/export/erasure ports before accepting data.

Free erasure nulls selected record/change payloads, preserves opaque anti-replay fences, disables the selected dataset consent and increments owner epoch before commit. Erasing all cloud data also revokes devices. It does not delete the free account or local data; account deletion independently invokes the same database privacy guards. Retained paid expiry data remains exportable while held; the 30-day exit/purge worker is completed with the retention task, not inferred from an API response.

PRM03-T01 change feed: owner-global committed sequence, current device/key/origin and enabled datasets only. First page captures a fixed high-water revision; later pages retain it, so interleaved writes appear in the next cycle without gaps. Each change includes its sequence and record revision; repeated delivery is safe for a client that applies only newer revisions. A signed 15-minute cursor binds owner/origin/device/schema and carries epoch/consent revision/last sequence/high-water. No cursor may select another account, device, dataset permission set or compacted history. An expired/compacted/erased cursor returns resnapshot-required, preserves pending local changes and never silently advances. New devices after compaction must obtain the PRM03-T03 consistent snapshot before requesting deltas.

PRM03-T02 push conflicts: POST /v1/cloud/sync/push reuses the atomic Apply and receipts. No silent last-arrival overwrite. A stale expected revision fails the full batch with base/current/proposed conflict data (expected revision, current revision/deleted flag, current payload or null when deleted, proposed payload, erased fence) and rolls back all writes/receipts/success stamps. Resolution is a new command at the current revision with a fresh operation ID; only independent documented operations (distinct dataset/UUID) merge in one batch. Changed operation-ID reuse conflicts; identical replay returns the original receipt. Conflict responses are transient and never persist deleted private content; receipts keep only operation/resource/result metadata.

PRM03-T03 import, consent and resnapshot: POST /v1/cloud/consent sets an explicit per-dataset opt-in or revoke. The server computes the mask and bumps the consent revision. The client never sets a mask or epoch directly. Revocation stops future commands and dispatch while preserving local and held cloud records. POST /v1/cloud/import/preview dry-runs guest vehicles, favorites and preferences with no writes. It preserves local UUIDs and the three-vehicle ceiling and reports create, update, delete, converge, conflict, quota, invalid or erased per operation. Cancellation discards the preview. Confirmation is an explicit Apply with fresh proof and versions. POST /v1/cloud/sync/snapshot returns revision-consistent full-record pages for one dataset. The first page captures the current revision. Later pages require the same revision and return resnapshot-required on intervening writes for explicit restart. The cursor binds owner, origin, device, dataset, revision, epoch and consent with a 15-minute TTL. New devices after compaction obtain this snapshot before deltas.

PRM03-T04 compaction and anti-resurrection: bounded indexed cleanup of changes and receipts older than 30 days with a durable compacted-through checkpoint in the same transaction. The owner row lock serializes parallel workers. A crash rolls back the floor and deletes together for safe retry. The floor advances to require resnapshot of stale cursors. Conservative retention or resnapshot refusal is preferred to resurrection. Erased-UUID and device-revocation fences are never cleaned. Every write path including foundation putTyped respects erased fences after physical tombstone removal. Old restores cannot recreate an erased UUID. Vehicles use archive. Shared hard-delete waits for the professional dependency preview. Personal erasure is distinct from business cascades. Restored infrastructure replays the separate external erasure ledger before serving. A table inside its own backup never proves operational recovery. Unknown proof never authorizes a purge. Missing configuration or outage never implies expiry.

PRM03-T05 two-client protocol: synthetic device clients A and B share one account with distinct device references. A creates, B edits while A is offline, stale A writes conflict with base, current and proposed data, and a fresh revision resolves. Identical operation-ID retries converge with replayed receipts. Pinned cursors hide interleaved writes until the next cycle. Revoked devices fail closed. Lapsed capability denies pushes and pulls. Compacted cursors require resnapshot. A restart uses new handler and store instances against durable PostGIS state. Bounded streams page with a fixed watermark. Synthetic server clients prove the backend protocol only, not Android device acceptance.

PRM04-T01 backup manifest: POST /v1/cloud/snapshots/manifest returns the acknowledged cloud revision with per-dataset counts, integrity checksum and exclusion list. Failure never reports local pending data as protected. No database dump. Future professional and rule datasets register their own export ports before inclusion.

PRM04-T02 snapshot storage: private snapshots/ prefix with immutable account, revision and snapshot-ID keys. No end-to-end encryption claim. Server-side privacy via restricted bucket and operator key recovery under the documented policy. Metadata-first fenced receipts in cloud_snapshots. Integrity readback of exact bytes before READY. Only READY snapshots are selectable. Corrupt, lost-response and crash orphans stay tracked as PENDING or FAILED for repair or purge. Duplicate snapshot IDs converge. Staging provider proof remains owed.

PRM04-T03 snapshot schedule: explicit consent opt-in drives periodic TickSnapshots with 24-hour cadence, 25-account ticks, seven-snapshot retention and ten-megabyte bounds. Ticks skip accounts without consent or lapsed entitlement with no duplicate cost. The owner row lock serializes restarts and quota races. Storage failures leave tracked orphans for retry. Cancelled ticks fail closed. SnapshotStatus exposes the last READY revision, unprotected changes, ready count and opt-in flag. New snapshots wait while cleanup holds the lock.

PRM04-T04 restore preview: owner-only listing of READY snapshots plus staged PreviewRestore with bounded decoding. Previews validate datasets, epoch, schema version, current conflicts and excluded records. Unknown datasets, duplicate IDs, invalid payloads and old schemas report incompatible issues without committing. Deleted snapshot records and erased current UUIDs count as excluded, never resurrected. Previews carry 15-minute expiry and current-revision binding for the T05 commit. Cancellation discards staged work with no writes.

PRM04-T05 restore commit: POST /v1/cloud/restore/commit applies a READY snapshot atomically with live owner, epoch and entitlement checks plus explicit merge policy and recoverable pre-restore revision. No security material import. Double confirmation with the same restore ID converges with replayed receipts. Stale previews, revoked devices and lapsed entitlement fail closed. Conflicts return base, current and proposed data without resurrecting erased UUIDs. Receipts carry only metadata.

PRM04-T06 snapshot erasure: Erase purges snapshot and restore metadata in the same transaction as record fences and deletes objects best-effort before commit. Outages fail closed with inventory preserved. Old snapshot IDs and stale devices stay blocked. Restored bytes beside purge receipts remain fenced via cloud_erased_ids. Unconfirmed bytes stay inventoried for retry. Staging provider proof remains owed.