docs+openspec: prior-art research (Organic Maps, Endurain, wanderer) and 15 proposals

Add docs/inspirations.md as the durable record of the 2026-07-05/06
prior-art research — per-project learnings with source paths, canonical
credit lines, and the changes each spawned — and extend the
acknowledgment lists in philosophy.md/architecture.md (Organic Maps,
Endurain, wanderer).

New OpenSpec changes (proposal/design/specs/tasks each):
- Organic Maps: elevation-profile-hardening, gpx-parser-robustness,
  hiking-time-estimate, poi-index, hiking-foot-profile
- Endurain: account-export, activity-duplicate-review,
  fit-parsing-hardening, activity-locations, self-hosting-guide,
  activity-privacy-controls
- wanderer: federation-hardening, link-share-tokens
- credits-page (user-visible acknowledgments)

Updated in-flight changes with wanderer prior-art sections:
route-federation, route-discovery.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Ullrich Schäfer 2026-07-06 07:23:00 +02:00
parent be4f7e4ae8
commit 5dd4968626
80 changed files with 2600 additions and 2 deletions

View file

@ -159,6 +159,35 @@ Implementation order: route-sharing schema changes (route-features section 1)
must be completed first. The explore page can be built in parallel but only
tested after visibility exists and at least one route is set to public.
## Prior art: wanderer (reviewed 2026-07-06)
Full analysis in `docs/inspirations.md`. wanderer runs trail discovery at
real scale (Meilisearch over PocketBase); their patterns don't change this
change's v1 scope but pre-answer its scaling questions:
- **Access control lives in the query layer, always.** They mint
per-session Meilisearch tenant tokens so the index itself enforces
`public OR author OR shared-with` — a client can't bypass it. Our
PostGIS equivalent: the `visibility = 'public'` predicate (D6) must be
part of the shared bbox-query helper, never a caller responsibility.
Worth an explicit regression test.
- **Clustering (currently a non-goal):** when dense areas force it,
their shape is proven — a server endpoint running `supercluster`
returning only `{id, point, bbox_diagonal}`, with a dynamic threshold
where the N largest-bounding-box routes render as actual polylines and
the rest cluster as points. A direct answer to the 50-result-limit
risk below when v1 outgrows it.
- **Recommendations without ML:** random-offset sampling over the
filtered result count ("surprise me") — cheap and effective.
- **Cross-instance discovery** (also a non-goal here): they index
federated-in remote trails as local stub records, searchable with
`is_federated`/`domain` facets — the likely shape for trails once
`route-federation` mirrors exist, rather than live fan-out search.
- Robustness details worth copying at implementation time:
antimeridian-aware bbox handling, a request-race guard on viewport
queries (stale responses discarded by request id), and a
payload-too-large fallback that shrinks page size.
## Risks / Trade-offs
- **50-result limit may frustrate users**: In dense areas (Alps, popular hiking