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

@ -0,0 +1,40 @@
## ADDED Requirements
### Requirement: Durable federation queue
Fedify's message queue SHALL be backed by PostgreSQL so that queued activities, inbox processing tasks, and retry state survive process restarts and deploys.
#### Scenario: Delivery survives a restart
- **WHEN** deliveries are queued and the journal container restarts before they complete
- **THEN** the deliveries execute after restart without loss
#### Scenario: Retry state persists
- **WHEN** a delivery has failed twice with backoff pending and the process restarts
- **THEN** the retry continues on schedule rather than starting over or disappearing
### Requirement: Inbound replay defense
The Journal SHALL record processed inbound activity IRIs (retained at least 30 days) and SHALL drop duplicate activities idempotently before any side effects.
#### Scenario: Replayed activity is a no-op
- **WHEN** the same signed Like activity is delivered twice
- **THEN** the second delivery produces no state change and is counted as a dropped duplicate
### Requirement: Instance blocklist
The Journal SHALL support blocking federation instances by domain, enforced at inbox processing (activities dropped without an error oracle), delivery enqueue (recipients filtered), and outbox polling/actor fetch (refused). Blocking SHALL be manageable via a documented operator procedure.
#### Scenario: Blocked instance is inert in both directions
- **WHEN** a domain is added to the blocklist
- **THEN** its activities are silently dropped, no deliveries are sent to it, and its actors/outboxes are not fetched
### Requirement: Published federation protocol documentation
The repository SHALL contain a `FEDERATION.md` documenting actor discovery, object and activity types with JSON examples, addressing rules, signature and deduplication expectations, delivery retry policy, and moderation semantics, kept current as federation capabilities change.
#### Scenario: Third-party implementer can interoperate
- **WHEN** another project implements against `FEDERATION.md`
- **THEN** the documented flows (follow, create fan-out, dedup) behave as described
### Requirement: Federation delivery observability
The Journal SHALL expose metrics for delivery outcomes, queue depth, and inbox drops (duplicate/blocked), surfaced on the monitoring dashboard.
#### Scenario: Operator sees delivery health
- **WHEN** deliveries to an unreachable instance keep failing
- **THEN** failure counts and queue depth are visible on the dashboard

View file

@ -0,0 +1,16 @@
## MODIFIED Requirements
### Requirement: Push delivery on local activity create
The Journal SHALL deliver a `Create(Note)` activity to every accepted remote follower's inbox when a local user with `profile_visibility = 'public'` creates a new `public` activity. Delivery queueing and retry state SHALL be persistent: queued deliveries and scheduled retries survive process restarts.
#### Scenario: New public activity fans out
- **WHEN** a local user with N accepted remote followers creates a new public activity
- **THEN** N delivery jobs are enqueued (one per follower's inbox), each retrying with exponential backoff on 5xx, giving up after a documented retry budget
#### Scenario: Rate-limited per remote host
- **WHEN** multiple deliveries target the same remote host
- **THEN** they are rate-limited so we never exceed 1 request per second per remote host (configurable; chosen for safety, not throughput)
#### Scenario: Fan-out survives a deploy
- **WHEN** a deploy restarts the journal while fan-out deliveries are queued or awaiting retry
- **THEN** the deliveries complete after the restart without loss