ADR 0027: Place Label Cache Staleness And Title Freeze
Status: accepted Date: 2026-05-22
Context
Reverse place lookup labels are derived metadata from local datasets or optional providers. Local gazetteer datasets can be imported, replaced, or updated. New versions may rename places, change hierarchy, improve coordinates, remove entries, or alter attribution requirements.
Automatic album suggestions and generated titles may have used older cached labels. If Memories silently updates accepted album titles when datasets change, it risks rewriting owner-visible curation and breaking trust. If it never marks labels stale, users and operators cannot tell when place data may be outdated.
The cache policy must distinguish three things:
- provider/dataset cache health;
- pending/generated suggestions that may be safely regenerated;
- accepted albums and exported provenance that represent historical owner decisions.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A. Always recompute labels on dataset update | Existing labels/titles update automatically | Freshest labels | Surprising title changes; breaks provenance; can overwrite owner intent |
| B. Never mark old labels stale | Labels remain forever unchanged | Stable and simple | Operators/users cannot identify outdated provider data |
| C. Mark stale, freeze accepted titles | Dataset update marks affected cache entries stale; pending suggestions may regenerate; accepted album titles/provenance remain frozen unless owner acts | Preserves trust while exposing staleness | Requires stale/superseded state and regeneration UX |
| D. Delete cache on update | Force all lookups to rebuild | Simple freshness model | Loses inspectability and historical provenance unless separately copied |
Decision
Use mark-stale plus title freeze.
When a local gazetteer dataset/provider version changes:
- Core records the new dataset/provider identity and import event.
- Cached place labels derived from older dataset/provider versions are marked
staleor superseded according to scope that Core can identify. - New lookup requests use the current active dataset/provider version.
- Pending/unaccepted automatic album suggestions may be regenerated or superseded using the newer labels, with provenance explaining the change.
- Accepted album titles and accepted suggestion provenance remain frozen. They are not silently renamed or rewritten by a dataset update.
- Owners may explicitly regenerate a generated-title suggestion, edit an album title, or accept a proposed title refresh later.
- Export includes the frozen title/provenance and stale/superseded state where relevant.
Cached labels need lifecycle states such as active, stale, superseded, and failed/unavailable where useful. A stale label may remain visible where it is part of historical provenance, but new title generation should prefer current active lookup results.
Consequences
Positive
- Preserves owner trust: accepted albums do not change because a dataset changed.
- Keeps historical titles inspectable and exportable.
- Allows operators/users to see when cached place data may be outdated.
- Supports safe regeneration for pending suggestions and future explicit title-refresh workflows.
Negative / Costs
- Requires stale/superseded cache states and provenance UI.
- Requires distinguishing pending suggestions from accepted albums.
- Some accepted albums may keep older place names until the owner updates them.
- Dataset update jobs need to identify affected cache entries where practical.
Revisit Triggers
Revisit this decision if:
- Users strongly prefer automatic accepted-title refreshes and accept the risk.
- Provider terms require attribution/license updates to be surfaced differently for old cached labels.
- Cache staleness tracking becomes too expensive for large datasets.
- Public sharing introduces stronger requirements for updating displayed attribution or place labels.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference