generated from coulomb/repo-seed
308 lines
10 KiB
Markdown
308 lines
10 KiB
Markdown
---
|
||
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) |