1 ADR 0028 reverse lookup precision policy
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0028: Reverse Lookup Precision Policy

Status: accepted Date: 2026-05-22

Context

Reverse place lookup can use precise coordinates, rounded coordinates, centroids, radii, bounding boxes, or spatial envelopes. Automatic album suggestions need useful place titles for clusters, but exact per-photo GPS coordinates are sensitive and often unnecessary for an album title. Even local cache/log/provenance rows should avoid more precision than the feature needs.

This decision must balance:

  • title quality, especially for venues/toponyms;
  • privacy and low surprise;
  • inspectable provenance;
  • provider-neutral lookup contracts;
  • future optional external online providers, where precision disclosure is even more sensitive.

Options Considered

Option Summary Benefits Costs / Risks
A. Always exact coordinate lookup Use raw media GPS or exact cluster centroid Best possible local precision Stores/logs/exposes more precision than needed; bad default for online providers
B. Always coarse area lookup Only use broad rounded/envelope inputs Strong privacy Poor venue/toponym title quality
C. Privacy-first escalation Start with cluster envelope or centroid+radius; store precision class; escalate to narrower local lookup only when needed and allowed Balances privacy and title quality More logic/provenance states
D. Provider decides precision Let each provider adapter choose Flexible Fragmented privacy behavior; hard to reason about

Decision

Use privacy-first precision escalation.

For automatic album title generation:

  1. Core should prefer a cluster-level spatial envelope, bounding box, or centroid plus radius instead of raw per-photo GPS points.
  2. Lookup requests and cached labels must record a lookupPrecisionClass, such as envelope, centroid_radius, rounded_coordinate, exact_coordinate, or fallback.
  3. Album title lookup should start with envelope or centroid_radius precision.
  4. Core may perform a narrower local lookup, such as rounded_coordinate or exact_coordinate, only when:
    • the feature needs a narrower venue/locality candidate;
    • the media owner is authorized for the underlying location metadata;
    • the provider is local, or an external provider has explicit operator enablement and disclosure for that precision class;
    • provenance records the precision class used.
  5. External online providers must default to the least precise useful input and require explicit disclosure before any exact-coordinate lookup is allowed.
  6. Normal logs should avoid exact coordinates and should prefer precision classes, provider IDs, and coarse envelope identifiers unless debug mode is explicitly enabled.

For regional parent album titles, precision class is not the same as containment evidence. A centroid_radius lookup can find nearby toponyms, but point-derived synthetic buffers must not by themselves justify a narrow city/village title when child/event anchors disagree. Regional title selection needs common hierarchy, derived administrative coverage, validated geographic-area evidence, child-place summary, or fallback.

This policy does not reduce Core's authoritative stored media coordinates. It governs reverse lookup requests, cached labels, provider calls, generated title provenance, and logs.

Consequences

Positive

  • Avoids normalizing exact per-photo GPS disclosure for album titles.
  • Keeps place title provenance honest about how precise the lookup was.
  • Allows venue-level quality when local data and owner policy justify narrower lookup.
  • Creates a clear additional disclosure boundary for external online providers.

Negative / Costs

  • Requires precision-class modeling in requests/cache/provenance.
  • Title generation may need multiple lookup passes or fallback behavior.
  • Some venue labels may be missed if the policy stays at envelope precision.
  • External providers need per-precision disclosure and possibly separate configuration.

Revisit Triggers

Revisit this decision if:

  • Envelope/centroid lookup quality is too poor for automatic album titles.
  • Users prefer exact local lookup and accept the local cache/provenance sensitivity.
  • External online provider support requires stricter anonymization/proxying rules.
  • PostGIS queries make precision classes too coarse to express actual lookup behavior.