bf9787e56a
Gap analysis of docs/architecture.md against openspec/ and docs/ideas/ found the envisioned-but-uncaptured remainder. This commit captures it: New OpenSpec change (validated): - route-federation — the collaboration half of the federation vision: routes as dereferenceable trails:Route objects, Create/Update fan-out, Invite/Accept collaboration mirroring (arch decision #2), cross-instance Planner edits via HTTP-Signature-requested scoped tokens (decisions #3/#12), mirror sync healing (#16). Depends on social-federation §6 + route-sharing; carries the 2026-06-07 soak lessons as design constraints. New docs/ideas/ explorations: - instance-administration — registration toggle, suspend/ban, federation blocklists, reports (moderation now gates the federated comments idea) - social-interactions — local likes + comments (don't exist even locally; the foundation federated kudos/comments attach to) - activity-participants — group tagging with confirm/decline + federated mentions (the participants jsonb column is an untyped stub) - multi-day-collections — architecture open question #1, directions evaluated architecture.md cleanup: - Mastodon-compat section annotated with shipped/captured state + the live-soak interop lessons (attachment arrays, tombstones, 10s timeout, no backfill) - api.trails.cool removed (contradicted resolved decision #18) - Phase 1 ticked (shipped); Phase 2/3 items annotated with where each is tracked; specs/ → openspec/, activity.* → journal.*, cx21 → cx23 - brouter-web open question marked resolved-in-practice; new section pointing to where the unshipped vision is tracked Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
## Context
|
|
|
|
Transcribes and refines architecture.md Resolved Decisions #2 (route
|
|
mirroring), #3 (cross-instance edits), #12 (cross-instance auth) and
|
|
#16 (delivery retry/sync healing) into a buildable change, on top of
|
|
what `social-federation` shipped: Fedify mounted in the journal,
|
|
per-user keys, the narrow inbox, NodeInfo-based trails-instance
|
|
discovery, push delivery via pg-boss, and the hard-won serialization
|
|
lessons (attachment arrays, tombstones, async queue, dereferenceable
|
|
objects).
|
|
|
|
Status: drafted ahead of implementation (2026-06-07) to capture the
|
|
architecture vision as a concrete change; revisit against reality once
|
|
social-federation §6/§7 and route-sharing have landed.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- A public route is a dereferenceable AP object at its canonical URL.
|
|
- Alice (instance A) shares a route with Bob (instance B): Invite →
|
|
Accept → B holds a mirror that stays current via Update fan-out.
|
|
- Bob edits Alice's route in a Planner session; the save lands on A as
|
|
a new version crediting Bob — no drafts on B (canonical-owner model).
|
|
- Mirrors self-heal after extended downtime via periodic sync check.
|
|
|
|
**Non-Goals:**
|
|
- Mastodon rendering of routes (trails-to-trails only).
|
|
- Federated forking, federated route discovery/search.
|
|
- Moving Planner sessions between instances (a session lives on one
|
|
Planner; only the *save destination* is remote).
|
|
|
|
## Decisions
|
|
|
|
### Decision: Canonical owner, mirrors as read caches (arch #2)
|
|
|
|
The owner's instance is the single source of truth. Collaborator
|
|
instances store mirrors — metadata + latest GPX — updated by `Update`
|
|
fan-out, used for display and as the seed when opening an edit session
|
|
while A is reachable; stale mirrors are explicitly labeled in the UI
|
|
when the sync check can't reach the origin.
|
|
|
|
### Decision: Edits go straight to the owner (arch #3, #12)
|
|
|
|
Bob's instance never stores a draft. The edit flow:
|
|
1. B requests a scoped edit token from A
|
|
(`POST /api/federation/routes/:id/edit-token`, HTTP-Signature
|
|
signed by Bob's actor key; A verifies Bob is a collaborator).
|
|
2. A issues the same shape of scoped JWT the local edit-in-planner
|
|
flow uses (route id, permissions, expiry, jti) — single-use
|
|
enforcement via the existing `consumed_jwt_jti` table.
|
|
3. B opens the Planner with A's callback URL + token; the existing
|
|
callback endpoint on A accepts the save and records Bob's actor IRI
|
|
as contributor (contributors become IRIs, matching the route
|
|
metadata envelope in arch #8).
|
|
|
|
### Decision: Vocabulary — custom `trails:Route` object, standard activity wrappers
|
|
|
|
`Create`/`Update`/`Invite`/`Accept` are standard AS2 activities; the
|
|
object is a custom type under the trails JSON-LD context (namespace
|
|
served from the instance, e.g. `https://trails.cool/ns#Route`) carrying
|
|
the metadata envelope (distance, elevation, day breaks, routing
|
|
profile, contributors) plus a GPX `Document` attachment. Soak lesson
|
|
applied: every shape verified against a real second instance before
|
|
merge, arrays for one-element collections, objects dereferenceable
|
|
from day one.
|
|
|
|
### Decision: Trails-to-trails gating reuses the §6 check
|
|
|
|
Same NodeInfo `software.name` allowlist as outbound follows; route
|
|
activities are neither delivered to nor accepted from non-trails
|
|
instances. (The Wanderer-interop idea would widen this allowlist —
|
|
explicitly out of scope here.)
|
|
|
|
### Decision: Sync check is a pg-boss cron, owner-driven re-fetch
|
|
|
|
Daily job on the *mirror-holding* instance: for each mirror whose
|
|
`last_update_at` predates its origin's advertised `updated` (HEAD/GET
|
|
on the canonical object), re-fetch and reconcile. Covers the
|
|
"instance down > 72h, Update lost" case in arch #16.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- **Custom vocabulary is an interop commitment** — version the
|
|
context document; additive evolution only.
|
|
- **Token issuance endpoint is a new authenticated surface** —
|
|
HTTP-Signature + collaborator check + rate limit + audit log;
|
|
security-review gate before enabling (same staged-flag pattern as
|
|
FEDERATION_ENABLED, possibly its own ROUTE_FEDERATION_ENABLED).
|
|
- **Tombstone semantics apply to routes too** (2026-06-07 soak
|
|
lesson): unsharing/unpublishing federates a retraction only on an
|
|
actual public/shared→not transition, and re-publishing after a
|
|
Delete won't resurrect mirrors that processed it.
|
|
- **Mirror divergence** if a save lands while fan-out is mid-flight —
|
|
versions are sequential on the owner; mirrors always converge to the
|
|
owner's latest (last-write-wins on the mirror, never on the origin).
|
|
|
|
## Open Questions
|
|
|
|
- Mirror storage: dedicated `route_mirrors` table vs provenance
|
|
columns on `routes` (the activities precedent says columns +
|
|
`remote_origin_iri UNIQUE`; routes carry more state — versions?
|
|
Probably mirror latest-only, no version history on mirrors).
|
|
- Does `Invite` target the user or the instance? (User — but the
|
|
Accept must be signed by the invited actor; what happens when the
|
|
user moves instances?)
|
|
- Contributor identity display for remote contributors (handle?
|
|
cached display name? same remote_actors cache?).
|
|
- Whether the planner needs to know anything at all (ideally zero
|
|
changes — callback URL + token are opaque to it already).
|