coulomb/shard-wiki
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
81cfce10d247a3b02e8fa1d0ecb9210f7d14e392
shard-wiki/workplans/SHARD-WP-0002-federation-architecture.md

10 KiB
Raw Blame History

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on, state_hub_workstream_id
id type title domain repo status owner topic_slug created updated depends_on state_hub_workstream_id
SHARD-WP-0002 workplan federation architecture design whynot shard-wiki active tegwick whynot 2026-06-08 2026-06-08
SHARD-WP-0001
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

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

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

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

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

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

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

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

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

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

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)
Reference in New Issue View Git Blame Copy Permalink