trails/openspec/changes/route-federation/design.md

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.)

Split-domain interop: the check runs against the actor IRI's host (server domain) after WebFinger resolution, never the handle's domain — remote instances may run Hollo/Mastodon-style split domains. See docs/ideas/split-domain-handles.md.

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.

Prior art: wanderer (reviewed 2026-07-06)

Full analysis in docs/inspirations.md. wanderer is the only other shipped ActivityPub-for-trails implementation; three findings bear on this design:

• Object model contrast. wanderer federates trails as plain Notes — metrics as bespoke tag[] entries, GPX as a Document attachment. That validates our GPX-as-Document choice but is otherwise the opposite of the trails:Route decision above. Their model is lossy (stringified metrics, 3-photo cap) and needs string parsing to consume; ours is structured but renders as nothing on non-trails platforms. Consideration for the vocabulary decision: emit a Note-compatible fallback alongside trails:Route (readable content HTML + image/GPX attachments on the same object). wanderer proves the Note shape renders well in Mastodon; carrying it costs little and keeps the "Mastodon rendering" non-goal a presentation choice rather than an architectural wall.
• wanderer interop is an adapter, not an allowlist tweak. The §6 gating note ("widen the allowlist") understates it: accepting wanderer content means parsing metric-tags out of Notes and emitting shapes they parse back. Feasible — their social layer (WebFinger, per-user keys, authorized fetch, Follow/Accept) matches ours — but it's a dedicated compatibility layer. Stays out of scope; now with an accurate size estimate.
• Operational prerequisite. wanderer's fire-and-forget delivery (no queue/retry) is the cautionary tale for mirror consistency: this change's Update fan-out and sync-healing assume durable delivery. The federation-hardening change (durable Fedify queue, replay dedup, instance blocklist) should land before route mirrors; mirror sync must also respect the blocklist (don't re-fetch origins on blocked domains).

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).