docs backend PHOTO_CAPTURE_CONTRACT

Photo capture authorization contract

Current initial-policy amendment: ADR-021 / PRM15–PRM21 supersedes mandatory 150m/GPS contribution admission and proximity-based price confidence. Identity, media, privacy and source-integrity checks remain. Historical location evidence and optional nearby geometry retain their original scope; future mandatory proximity is PRM22 DEFERRED.

P37-PC01, 2026-10-07. Implements B-BR-PC01/PC06 from the photo contribution plan before Android consumers. Signed POST /v1/photo-captures uses the existing verified identity nonce, account gate, quota and idempotency runner. It accepts client_capture_id, canonical station_id and the existing location-evidence shape. Server-time freshness, finite accuracy/coordinates and real reviewed-station PostGIS distance must pass; maximum radius is 150m. Exact fixes are discarded after evaluation and never stored in the authorization table or response.

The server returns an opaque owner/key/station-bound authorization, a two-minute camera-opening deadline and a 24-hour submission deadline. Replaying an identical idempotency request never extends these deadlines; a different body conflicts. The receipt records only ids, times and the accepted policy. Camera opening after expiry requires a new authorized interaction. Actual capture time must fall within the authorization's camera window; it is preserved through crop and retry. Upload binding consumes the authorization for one evidence session; several selected fuel observations may reference that same session, while rebinding to a different session/account/key/station fails. Expiry and revoked identity fail closed. Metadata-only submissions retain their existing behavior.

Controlled Android tests may inject test-only eligibility through a debug/instrumentation source set. It never grants server proximity, ships in release, bypasses signed backend checks or publishes historical corpus prices. Device test results distinguish this controlled path from genuine physical station acceptance.

Risk: critical location/auth/privacy/SQL. Immediate tests: missing/denied/mock/stale/coarse/negative/nonfinite fixes, 149.9/150/150.1m, absent/unreviewed station, clock skew, auth/owner/key/station isolation, idempotency/conflict/expiry, concurrent receipt use, real PostGIS and migration/recovery. No completion claim until these pass.