--- id: SHARD-WP-0002 type: workplan title: "federation architecture design" domain: whynot repo: shard-wiki status: active owner: tegwick topic_slug: whynot created: "2026-06-08" updated: "2026-06-08" depends_on: - SHARD-WP-0001 state_hub_workstream_id: "2af4c46d-cbfd-40ea-a94b-d9e60b0f9945" --- # SHARD-WP-0002 — Federation architecture design ## Goal Produce a **federation architecture specification** for shard-wiki: positioning against prior art (Federated Wiki, git-backed wikis, ActivityPub), documented **decisions and tradeoffs**, and ADR-ready design notes that resolve the open questions raised by `research/260608-federation-concepts/` and UseCaseCatalog UC-26–UC-33. Primary deliverable: `spec/FederationArchitecture.md` (created and filled by this workplan's tasks). ## Context - Research: `research/260608-federation-concepts/findings.md` - Use cases: `spec/UseCaseCatalog.md` § A (UC-26–UC-33) - Aspiration: `INTENT.md` (orchestrator, not engine; mechanism over policy) - Related workplan: `SHARD-WP-0001` (page resolution, namespaces, overlays, provenance — federation architecture must align with, not duplicate, those outputs) **Non-goal:** Implement federation. This workplan produces architecture and decision records only. ## Decision topics (overview) | Topic | Key tradeoff | Primary UCs | |-------|--------------|-------------| | Orchestrator positioning | Adapter layer vs fedwiki-style homogeneous network | UC-02, UC-26 | | Remix primitives | Fork vs overlay vs import vs link-only | UC-04, UC-26, UC-29 | | Equivalent page identity | Title/path/alias/graph matching; chorus vs canonical | UC-27, UC-07 | | History model | Per-shard journal vs Git coordination journal vs both | UC-29, UC-33 | | Union composition | Server orchestrator vs client composition | UC-05, UC-27 | | Change notification | Git ping, ActivityPub, poll — adapter transports | UC-31 | | Space lifecycle | Permanent vs ephemeral; archive and carry-forward | UC-28, UC-30 | | Transclusion depth | Whole-page projection vs inline span | UC-03, UC-32 | | Consensus presets | Spread, merge, designated canonical — policy not core | UC-07, UC-27 | | Capability matrix | Which federation ops require which adapter capabilities | UC-02–UC-07 | --- ## Architecture positioning and boundaries ```task id: SHARD-WP-0002-T1 status: todo priority: high state_hub_task_id: "ea8fdb22-6c7f-4ac1-9799-1346abf3c3b7" ``` Write the opening sections of `spec/FederationArchitecture.md`: - shard-wiki as **orchestration layer** over heterogeneous shards (contrast Federated Wiki homogeneous JSON sites, ikiwiki homogeneous git wikis, ActivityPub activity streams). - Explicit **compare, do not equate** mapping from federation research §6. - Architectural boundaries: what core owns vs adapters vs UI vs policy config. - Relationship to `SHARD-WP-0001` outputs (resolution, namespaces, overlays). **Tradeoffs to document:** Central Git coordination journal vs fully decentralized peer sync; browser-composed union vs server-side orchestrator for agents/CLI. --- ## Remix primitives: fork, overlay, import, reference ```task id: SHARD-WP-0002-T2 status: todo priority: high state_hub_task_id: "fb7d4bce-5d2e-4602-9b63-85934d90e82d" ``` Define when each remix primitive applies and how they interact: | Primitive | Typical trigger | Writes to remote? | |-----------|-----------------|-------------------| | **Reference** | Link only | No | | **Projection** | Read remote page | No (cache optional) | | **Overlay** | Edit read-only shard | No until explicit apply | | **Import / fork** | Copy into writable shard | Source unchanged | Resolve federation research open question #1. Cover capability-limited shards (read-only, no diff/merge). Map to UC-26, UC-04, UC-29. **Tradeoffs:** Fedwiki fork-as-default vs overlay-before-mutation; copy cost and attribution portability vs link-only federation. --- ## Equivalent page identity and multi-version presentation ```task id: SHARD-WP-0002-T3 status: todo priority: high state_hub_task_id: "8f2a333d-ddcc-4cc6-b6ed-1ba9b178eee3" ``` Specify how shard-wiki identifies "the same topic" across shards: - Matching signals: normalized title, path, explicit alias table, link-graph equivalence, manual curator binding. - Presentation: chorus-of-voices (UC-27) vs designated canonical (policy). - Link to UC-07 divergence detection and reconciliation triggers. **Tradeoffs:** Automatic matching false positives vs manual curation burden; showing all versions vs default canonical with alternates visible. --- ## History, attribution, and coordination journal ```task id: SHARD-WP-0002-T4 status: todo priority: high state_hub_task_id: "5f39f48d-5142-4078-a84f-3245ec1add7e" ``` Define how edit history and attribution flow across federation operations: - Per-shard revision model (Git commit, engine history, fedwiki-style journal where applicable). - Information-space **coordination journal** role for cross-shard operations (fork, import, reconcile, space branch). - Portable attribution requirements for UC-29 (frictionless remix). **Tradeoffs:** Fedwiki journal-per-page vs Git-only; duplication of history vs reconstructibility from coordination journal; storage cost of embedded media on import. --- ## Union composition layer ```task id: SHARD-WP-0002-T5 status: todo priority: medium state_hub_task_id: "3ff71e11-d0e9-4fda-b916-d6c34c51aa51" ``` Decide where the **union view** is assembled: - Orchestrator API (server-side graph for agents, CI, non-browser clients). - Optional client-side composition (fedwiki-style browser pull) as a consumer pattern, not the only path. - Caching, freshness, and invalidation interaction with UC-03, UC-05, UC-31. **Tradeoffs:** Single composition point (simpler provenance) vs distributed composition (fedwiki resilience); cache staleness vs live-pull latency. --- ## Change notification and subscription transports ```task id: SHARD-WP-0002-T6 status: todo priority: medium state_hub_task_id: "9596e5e8-8d6b-4ed4-bcbc-ebb45e3168be" ``` Specify change-notification as an **optional adapter capability**: - Transports: git hook / pinger (ikiwiki), ActivityPub Create/Update (XWiki), WebDAV ETag, polling fallback. - What a subscription triggers: projection refresh, reconciliation queue, RecentChanges union entry (UC-31, UC-17). - Out-of-scope vs in-scope for v1. **Tradeoffs:** Push freshness vs implementation complexity; ActivityPub as notification-only vs content-bearing share; dependency on external fediverse infrastructure. --- ## Information space lifecycle ```task id: SHARD-WP-0002-T7 status: todo priority: medium state_hub_task_id: "38134064-51ce-4f5a-80bf-b2cfbe381c59" ``` Model lifecycle states for root entities / information spaces: - Active, read-only archived, retired (detached), merged-into-successor. - Carry-forward workflow (UC-28, UC-30): selective import from archived shard. - Space-level fork / branch (UC-33): coordination journal + shard config branch. **Tradeoffs:** First-class ephemeral "happenings" vs permanent spaces only; automatic archive vs manual; whether retirement deletes projections or preserves read-only union entries. --- ## Transclusion and projection depth ```task id: SHARD-WP-0002-T8 status: todo priority: medium state_hub_task_id: "5607732b-612a-4550-bb17-b8cd34979cf4" ``` Distinguish projection levels: | Level | UC | Behavior | |-------|-----|----------| | Whole-page projection | UC-03 | Lazy full page from remote shard | | Block/span transclusion | UC-32 | Inline embed with origin + freshness | | Link reference | UC-08 | Pointer only | Define provenance display requirements and staleness semantics for UC-32. Reference Xanadu transclusion patterns without adopting unbuilt Xanadu scope. **Tradeoffs:** Live transclusion fragility (link rot, remote down) vs snapshot on import; core orchestrator support vs Markdown extension + adapter. --- ## Consensus and reconciliation policy catalog ```task id: SHARD-WP-0002-T9 status: todo priority: medium state_hub_task_id: "adfca8b3-eb21-497d-9f51-65dc9269c810" ``` Document **configurable policy presets** (mechanism over policy): - Fedwiki-spread (versions coexist; popularity implicit). - Designated canonical shard (explicit write target). - Git-merge reconciliation (ikiwiki-style). - Overlay-only (no destructive merge on read-only sources). - Vote-to-merge / editorial gate (optional, UI-layer). Map presets to UC-07, UC-27. Core provides primitives; policy selects preset. **Tradeoffs:** Default policy for L0 open mode vs team mode; exposing conflicts vs auto-merge when backends support it. --- ## Federation operations capability matrix ```task id: SHARD-WP-0002-T10 status: todo priority: medium state_hub_task_id: "c7a93d06-8631-43b4-bc7f-1b0a1cd1436f" ``` Produce a capability matrix: which federation operations require which adapter capabilities (read, write, diff, merge, lock, version, publish, notify, transclude-source). Cross-check against INTENT capability-aware adapters principle. Identify graceful degradation paths for limited backends (read-only participant, projection-only, patch target). Feeds `spec/TechnicalSpecificationDocument.md` adapter contract section. --- ## Acceptance criteria - `spec/FederationArchitecture.md` exists with all ten topic sections and an explicit **decisions / deferred / open** table per topic. - Each decision honors INTENT: mechanism over policy, union without erasure, overlay before mutation, no silent remote mutation, shard sovereignty. - UC-26–UC-33 are traceable to architecture sections. - Conflicts or dependencies on `SHARD-WP-0001` outputs are listed (e.g. namespace model affects equivalent-page identity). - `SHARD-WP-0001` and `SHARD-WP-0002` can proceed in parallel where topics are independent; merge conflicts in spec are resolved before implementation workplan starts. ## Suggested task order 1. T1 positioning (frames everything) 2. T2 remix primitives + T3 equivalent identity (parallel) 3. T4 history model 4. T5 composition + T6 notification (parallel) 5. T7 lifecycle + T8 transclusion (parallel) 6. T9 policy catalog + T10 capability matrix (parallel, finalize doc)