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:
parent
be4f7e4ae8
commit
5dd4968626
80 changed files with 2600 additions and 2 deletions
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Add table
Add a link
Reference in a new issue