shard-wiki/spec/FederationArchitecture.md

FederationArchitecture

Status: draft for review · Date: 2026-06-15 · Deliverable of SHARD-WP-0002 (T1–T10, T17)

The federation design decisions for shard-wiki: what the union does. It records, per topic, a decision with rationale, tradeoffs, and a Decided / Deferred / Open footer. It references spec/CoreArchitectureBlueprint.md (the whole-system architecture) and spec/FederationRequirements.md (yawex-derived ADRs) rather than restating them; the adapter contract (what a backend must expose) is the companion deliverable in spec/TechnicalSpecificationDocument.md §A (T11–T16, T18). UC references → UseCaseCatalog.md.

Cross-cutting invariants assumed throughout (blueprint §2): orchestrator-not-engine (I-1), three-state canonical/derived (I-2), capability-as-data (I-3), union-without-erasure (I-4), overlay-before-mutation (I-5), git-addressable coordination (I-6), mechanism-over-policy (I-7), graceful degradation (I-8), identity≠placement (I-9), history-as-floor (I-10), authz-in-core (I-11), tenant-partitioned derived state (I-13).

---

T1 — Orchestrator positioning & boundaries

Decision. shard-wiki is an adapter-layer orchestrator in a star shape (many sovereign shards ↔ one information space), not a homogeneous federation network. It compares, does not equate (Federated Wiki homogeneous JSON sites, ikiwiki homogeneous git wikis, ActivityPub activity streams are models it can speak, §T17 — not shapes it imposes). Core owns: the union, the coordination journal, projection, overlay, resolution, authorization. Adapters own backend specifics; UI and editorial policy live outside core. (Blueprint §1, §5; UC-02, UC-26.)

Decided: star orchestrator; compare-not-equate; core/adapter/UI/policy boundaries. Deferred: the reference UI (L6) is out of scope here. Open: none.

T2 — Remix primitives: reference / projection / overlay / import-fork

Decision. Four primitives, escalating in commitment; overlay-before-mutation is the default write path (I-5), fork is one federation model (§T17) not the default for editing:

Primitive	Trigger	Writes remote?	Coordination-canonical?
Reference	link only	no	no (a link in content)
Projection	read remote page	no (cache)	no (derived)
Overlay	edit a sub-write-through shard	not until explicit apply	yes (decision log)
Import / fork	copy into a writable shard / fork-with-provenance	source unchanged	yes (fork event)

(Blueprint §8.2; FederationRequirements ADR-05; UC-04, UC-26, UC-29.)

Decided: the four primitives + overlay-default. Deferred: fork-attribution portability format. Open: whether "import" and "fork" are one primitive with a flag or two (impl spike).

T3 — Equivalent-page identity & multi-version presentation

Decision. Separate identity (stable handle), placement (N paths/shards), and equivalence (content-fingerprint / span-set overlap across identities), per FederationRequirements ADR-01/ADR-02 (I-9). Equivalence signals: normalized title/path, alias table (coordination-canonical), link-graph overlap, fingerprint, curator binding. Default presentation = chorus-of-voices (all equivalent versions, attributed); designated- canonical is a policy preset (§T9). Divergence is data in the provenance envelope (I-4), detected as core mechanism (blueprint §8.6). (UC-07, UC-27; UC-46.)

Decided: identity/placement/equivalence split; chorus default. Deferred: fingerprint algorithm + blocking params (blueprint O-1). Open: curator-binding UX (L6).

T4 — History, attribution & the coordination journal

Decision. Each information space has a git-addressable, event-sourced coordination journal (blueprint §8.1, I-6/I-10): coordination-canonical decisions (overlay/binding/alias/ merge/fork) are append-only events; current state is a derived fold. One append authority per space gives a total order (read-your-writes across instances). Per-shard native history is adopted (git-native), supplemented (DB/CRDT internal → journal begins-now/mirrors), or imported (open file history backfilled) per the history-portability axis (TSD §A T13). Attribution is portable on the event (UC-29). (UC-29, UC-33.)

Decided: event-sourced journal + per-space append authority + adopt/supplement/import. Deferred: per-space log sharding for extreme write rates (blueprint O-12). Open: none.

T5 — Union composition layer

Decision. The server-side orchestrator union is primary — the derived tier (union graph, indexes, projections) is composed in core for agents/CLI/non-browser consumers (blueprint §8.4), incrementally maintained (not recomputed, §8.7), tenant-partitioned (I-13). Client-side composition (Federated-Wiki-style browser pull) is a supported consumer pattern over the same union, not the only path. Freshness/caching per §8.8. (UC-05, UC-27, UC-03, UC-31.)

Decided: server-primary, client-optional; incremental, partitioned. Deferred: client SDK shape. Open: persisted-union digest granularity (blueprint O-4, B-4 checker).

T6 — Change notification & subscription transports

Decision. Change-notification is an optional adapter capability (notify), and it is the primary driver of incremental maintenance (blueprint §8.7/§8.8). Transports, per profile: git hook / ikiwiki-style ping, ActivityPub Create/Update, webhook, WebDAV/HTTP ETag or Last-Modified poll, plain polling fallback. A notification → invalidate affected entries

• enqueue delta refresh + a RecentChanges union entry (FederationRequirements ADR-03; UC-31, UC-17). Rate-limited shards favour event-driven + long TTL (operational-envelope axis).

Decided: notify = optional capability, drives incremental + RecentChanges; transport per profile. Deferred: ActivityPub as content-bearing (vs notify-only) — start notify-only. Open: fediverse-dependency posture for v1.

T7 — Information-space lifecycle

Decision. Root entities have lifecycle states: active → read-only-archived → retired (detached), and merged-into-successor. Carry-forward is selective import from an archived shard (UC-28, UC-30). Space-fork / branch (UC-33) = branch the coordination journal + shard-config (a fork event, §T2/§T17 fork+journal model). Retirement preserves read-only union entries by default (history-as-floor, I-10), never hard-deletes projections. (UC-28, UC-30, UC-33.)

Decided: the lifecycle states + carry-forward + space-branch; retire-preserves. Deferred: ephemeral "happenings" as a first-class mode. Open: GC policy for retired-space derived tier.

T8 — Transclusion & projection depth

Decision. Transclusion is one reference-not-copy primitive over the addressable union (blueprint §8.4), at three depths:

Level	UC	Behaviour
Whole-page projection	UC-03	lazy full page from a remote shard (replication-projection)
Block/span transclusion	UC-32	inline embed by span address, with origin + freshness
Link reference	UC-08	pointer only (ADR-06)

Every transcluded artifact carries provenance + staleness (I-4, §8.8); live-transclusion fragility (link rot / remote down) degrades to last-known + an unavailable/stale marker (blueprint O-11). Span-level authz under transclusion = the stricter of source/host (O-10). Reference-not-copy unifies Xanadu transclusion, ZigZag clone, embeds, synced blocks, Trilium note-clone, literate named-chunk. (UC-03, UC-32.)

Decided: one primitive, three depths, provenance+staleness mandatory. Deferred: snapshot- on-import vs live default (a policy). Open: span-authz composition (O-10), addressing (O-6).

T9 — Consensus & reconciliation policy catalog

Decision. Detection is core, resolution is policy (I-7, blueprint §8.6). Core always detects divergence and represents it as a coexisting (chorus) set; the resolution preset is configurable per space / per equivalence set:

• chorus-spread (versions coexist; default) · designated-canonical (explicit write target) · git-merge (where merge capability allows) · vote-to-merge / editorial gate (optional, L6-assisted) · overlay-only (no destructive merge on read-only sources).

(FederationRequirements ADR-03/ADR-05; UC-07, UC-27.)

Decided: the preset catalog; detection-core/resolution-policy. Deferred: vote/editorial gate mechanics (L6). Open: default preset per persona bundle (blueprint O-8).

T10 — Federation-operations capability matrix

Decision. Each federation operation requires a minimum verified capability profile (TSD §A T11/§6.6); below it, the op degrades along the named interaction axes (blueprint §6.5) rather than failing. The matrix (consuming the T11 vocabulary):

Federation op	Min capabilities	Degradation when absent
read / project	read	(floor — every shard)
transclude span	read + addressing≥span	whole-page projection only
overlay	read	always available (overlay is local)
write-through	write (+ merge for concurrent)	→ overlay/patch target
diff / 3-way merge	diff,merge	→ keep-both / chorus
notify-driven freshness	notify	→ validator-poll → TTL (§8.8)
native search delegate	native-query≥index	→ derived index over projection
publish / mirror	publish	→ read-only / static projection
fork+journal federation	read + history (any)	→ projection-only participant

Every backend, down to the Oddmuse flat-file floor, is usable as read-only / cache / projection / backup / patch target (I-8). This matrix and the T11 spectra are kept in sync (it consumes that vocabulary). (UC-02–UC-07.)

Decided: the op→capability matrix + degradation paths. Deferred: exhaustive per-op test vectors → the conformance suite (§6.6). Open: axis-interaction completeness (blueprint O-5).

---

T17 — Federation-model taxonomy (selectable / composable)

Decision. Federation is plural and composable, not one mechanism (blueprint §8.3). A space selects a model (composing per shard); the default is fork+journal over Git (the home case):

Model	Anchor	Coordination shape	Capability floor	UCs
Fork + journal (default)	Federated Wiki	copy-with-provenance + per-page action journal (story = replay)	read + journal	UC-26, UC-71, UC-72
VCS-replication + ping	ikiwiki	git clone/pull/push + change-ping	git-IS-store	UC-31, UC-33, UC-79
Query-time graph-join	Wikibase SERVICE	join remote graphs at query, no copy	native-query≥graph	UC-74
Feed aggregation	RSS/Atom	inbound feed → pages	read	UC-03
Activity streams	ActivityPub	Create/Update events (notify or content)	notify	UC-31
Engine-mirror	Wiki.js DB↔Git	engine mirrors its store to git	publish/mirror	UC-68, UC-69

The coordination journal (T4) is the fork+journal model's home; git IS the journal in VCS-replication and engine-mirror (forge wikis make git the store and journal, resolving the engine-mirror write-race). Models compose: e.g. fork+journal locally, query-join for a typed-graph shard, feed-aggregation for an external source. (Mechanism over policy, I-7.)

Decided: the six models, selectable per space + composable per shard, default fork+journal. Deferred: activity-streams content-bearing mode. Open: multi-model interaction edge cases (when two models touch one shard).

---

Consolidated decisions / deferred / open

• Decided (architecture-settling): star orchestrator (T1); overlay-default remix (T2); identity/placement/equivalence + chorus (T3); event-sourced journal + append authority (T4); server-primary incremental union (T5); notify-driven freshness (T6); space lifecycle (T7); reference-not-copy transclusion (T8); detection-core/resolution-policy preset catalog (T9); op→capability matrix (T10); selectable/composable federation models (T17).
• Deferred (to impl / L6 / persona bundles): reference UI; fork-attribution format; client SDK; vote/editorial mechanics; ephemeral spaces; ActivityPub content-bearing; default-preset bundles (O-8).
• Open (tracked in blueprint §12): O-1 equivalence blocking, O-4 union digest, O-5 axis interactions, O-6 addressing, O-8 presets, O-10 span-authz, O-11 unavailability, O-12 log throughput.

Acceptance (SHARD-WP-0002 federation half)

T1–T10 + T17 each have a decision record with a Decided/Deferred/Open footer; all honour INTENT; UC-26–UC-33, UC-56, UC-71–UC-72, UC-74, UC-79 trace here; the adapter-contract companion is spec/TechnicalSpecificationDocument.md §A (T11–T16, T18). Conflicts with SHARD-WP-0001 are none (FederationRequirements ADRs are consumed, not duplicated).