generated from coulomb/repo-seed
spec: promote federation UCs; add SHARD-WP-0002 architecture workplan
Promote UC-26 through UC-33 from federation research into UseCaseCatalog. Add SHARD-WP-0002 with ten decision topics (remix primitives, equivalent page identity, history, composition, notification, lifecycle, transclusion, consensus presets, capability matrix) targeting spec/FederationArchitecture.md.
This commit is contained in:
297
workplans/SHARD-WP-0002-federation-architecture.md
Normal file
297
workplans/SHARD-WP-0002-federation-architecture.md
Normal file
@@ -0,0 +1,297 @@
|
||||
---
|
||||
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
|
||||
---
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
Block a user