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:
11
SCOPE.md
11
SCOPE.md
@@ -22,7 +22,7 @@ Learnings update both SCOPE and INTENT where necessary.
|
|||||||
| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`) |
|
| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`) |
|
||||||
| Demand | NetKingdom integration asks captured, not yet negotiated |
|
| Demand | NetKingdom integration asks captured, not yet negotiated |
|
||||||
| Spec | Architecture blueprint drafted; UseCaseCatalog 25 UCs from research; PRD/TSD scaffolds |
|
| Spec | Architecture blueprint drafted; UseCaseCatalog 25 UCs from research; PRD/TSD scaffolds |
|
||||||
| Work | `SHARD-WP-0001` active — 6 design tasks, all todo |
|
| Work | `SHARD-WP-0001` active (6 tasks); `SHARD-WP-0002` active (10 tasks) |
|
||||||
|
|
||||||
## In Scope (today)
|
## In Scope (today)
|
||||||
|
|
||||||
@@ -52,6 +52,9 @@ live in core.
|
|||||||
|
|
||||||
## Current Planning
|
## Current Planning
|
||||||
|
|
||||||
Design work is tracked in `workplans/SHARD-WP-0001-yawex-requirements.md`.
|
Design work is tracked in `workplans/SHARD-WP-0001-yawex-requirements.md`
|
||||||
Specification outputs from that workplan land in `spec/`. Inbound integration
|
(yawex-derived resolution, namespaces, overlays) and
|
||||||
asks remain in `demand/` until reviewed and promoted into spec or workplans.
|
`workplans/SHARD-WP-0002-federation-architecture.md` (federation architecture,
|
||||||
|
decisions, tradeoffs). Specification outputs land in `spec/`. Inbound
|
||||||
|
integration asks remain in `demand/` until reviewed and promoted into spec or
|
||||||
|
workplans.
|
||||||
@@ -23,5 +23,6 @@ Focus: terms, architectural patterns, and **mapping to `shard-wiki` INTENT**
|
|||||||
|
|
||||||
## Status
|
## Status
|
||||||
|
|
||||||
Initial exploration complete. Findings may inform `spec/` and future
|
Initial exploration complete. Use cases promoted to `spec/UseCaseCatalog.md`
|
||||||
workplans; not yet promoted to specification.
|
(UC-26–UC-33). Federation architecture design tracked in
|
||||||
|
`workplans/SHARD-WP-0002-federation-architecture.md`.
|
||||||
@@ -337,20 +337,21 @@ data sovereignty** research, not direct prior art.
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7. Use-case seeds (not yet in UseCaseCatalog)
|
## 7. Use-case promotion (done 2026-06-08)
|
||||||
|
|
||||||
Candidates for future promotion from this research:
|
Promoted to `spec/UseCaseCatalog.md` as UC-26–UC-33. Architecture decisions
|
||||||
|
tracked in `workplans/SHARD-WP-0002-federation-architecture.md`.
|
||||||
|
|
||||||
| ID | Use case | Source |
|
| Research ID | Catalog UC |
|
||||||
|----|----------|--------|
|
|-------------|------------|
|
||||||
| UC-FED-01 | **Fork page from remote shard into writable shard** | Fedwiki fork; maps to overlay or import policy |
|
| UC-FED-01 Fork page from remote shard | UC-26 |
|
||||||
| UC-FED-02 | **View multiple versions of equivalent page** | Fedwiki chorus; union without erasure |
|
| UC-FED-02 View multiple versions of equivalent page | UC-27 |
|
||||||
| UC-FED-03 | **Carry forward pages from closed/archived shard** | Bounded conversation / reverse bit-rot |
|
| UC-FED-03 Carry forward from closed/archived shard | UC-28 |
|
||||||
| UC-FED-04 | **Remix with portable attribution** | Fedwiki journal; coordination journal |
|
| UC-FED-04 Remix with portable attribution | UC-29 |
|
||||||
| UC-FED-05 | **Time-bounded collaboration space** | Happening; optional space lifecycle policy |
|
| UC-FED-05 Time-bounded collaboration space | UC-30 |
|
||||||
| UC-FED-06 | **Subscribe to remote shard changes** | ikiwiki pinger, ActivityPub Create/Update |
|
| UC-FED-06 Subscribe to remote shard changes | UC-31 |
|
||||||
| UC-FED-07 | **Transclude remote span with live freshness** | Xanadu; projection + provenance |
|
| UC-FED-07 Transclude remote span | UC-32 |
|
||||||
| UC-FED-08 | **Git-branch a wiki information space** | ikiwiki branch; coordination journal fork |
|
| UC-FED-08 Git-branch information space | UC-33 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -46,9 +46,11 @@ See `INTENT.md` § Strategic Boundaries.
|
|||||||
|
|
||||||
- `research/260608-yawex-prior-art/findings.md` — federation design seeds from
|
- `research/260608-yawex-prior-art/findings.md` — federation design seeds from
|
||||||
prior art.
|
prior art.
|
||||||
|
- `research/260608-federation-concepts/findings.md` — Federated Wiki, git/AP
|
||||||
|
federation models; UC-26–UC-33 in `spec/UseCaseCatalog.md`.
|
||||||
|
|
||||||
## 8. Open Items
|
## 8. Open Items
|
||||||
|
|
||||||
Pending completion of `SHARD-WP-0001` design tasks and ratification of access
|
Pending completion of `SHARD-WP-0001` and `SHARD-WP-0002` design tasks and
|
||||||
model INTENT amendments. Detailed requirements will be expanded as spec tasks
|
ratification of access model INTENT amendments. Detailed requirements will be
|
||||||
complete.
|
expanded as spec tasks complete.
|
||||||
@@ -2,7 +2,8 @@
|
|||||||
|
|
||||||
Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-08
|
Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-08
|
||||||
|
|
||||||
Promoted from `research/260608-c2-wiki-origins/` and `research/260608-yawex-prior-art/`.
|
Promoted from `research/260608-c2-wiki-origins/`,
|
||||||
|
`research/260608-yawex-prior-art/`, and `research/260608-federation-concepts/`.
|
||||||
See InfoTechPrimers on coulomb.social for use-case catalog conventions.
|
See InfoTechPrimers on coulomb.social for use-case catalog conventions.
|
||||||
|
|
||||||
## Conventions
|
## Conventions
|
||||||
@@ -11,7 +12,7 @@ Each use case lists:
|
|||||||
|
|
||||||
- **Actor** — who initiates the action
|
- **Actor** — who initiates the action
|
||||||
- **Goal** — observable outcome
|
- **Goal** — observable outcome
|
||||||
- **Source** — research lineage (`c2`, `yawex`, `intent`, or combined)
|
- **Source** — research lineage (`c2`, `yawex`, `federation`, `intent`, or combined)
|
||||||
- **Notes** — shard-wiki-specific constraints or open design points
|
- **Notes** — shard-wiki-specific constraints or open design points
|
||||||
|
|
||||||
Priority hints: **MVP** = likely early value; **Later** = important but not first slice.
|
Priority hints: **MVP** = likely early value; **Later** = important but not first slice.
|
||||||
@@ -88,7 +89,90 @@ shard-wiki delegates authentication, owns authorization
|
|||||||
**Goal:** Identify when equivalent pages in different shards have diverged and
|
**Goal:** Identify when equivalent pages in different shards have diverged and
|
||||||
reconcile them under explicit policy.
|
reconcile them under explicit policy.
|
||||||
**Source:** intent
|
**Source:** intent
|
||||||
**Notes:** Union without erasure — conflicts visible, not hidden.
|
**Notes:** Union without erasure — conflicts visible, not hidden. Complements
|
||||||
|
UC-27 (multi-version view) and SHARD-WP-0002 consensus-policy task.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-26 — Fork page from remote shard into writable shard
|
||||||
|
|
||||||
|
**Actor:** Author
|
||||||
|
**Goal:** Copy a page from a remote or read-only shard into a local writable
|
||||||
|
shard for independent editing, with provenance preserved.
|
||||||
|
**Source:** federation, intent
|
||||||
|
**Notes:** Fedwiki fork primitive. shard-wiki may realize as import, overlay
|
||||||
|
seed, or writable copy per policy — distinct from UC-04 (overlay without copy)
|
||||||
|
and UC-03 (projection only). Fork vs overlay vs import decided in
|
||||||
|
`SHARD-WP-0002`.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-27 — View multiple versions of equivalent page
|
||||||
|
|
||||||
|
**Actor:** Reader
|
||||||
|
**Goal:** See coexisting versions of the same topic from different shards or
|
||||||
|
authors without collapsing them into one canonical page.
|
||||||
|
**Source:** federation, intent
|
||||||
|
**Notes:** Fedwiki "chorus of voices"; INTENT union without erasure. Equivalent-
|
||||||
|
page identity model TBD (`SHARD-WP-0002`). Links UC-07 divergence detection.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-28 — Carry forward pages from closed or archived shard
|
||||||
|
|
||||||
|
**Actor:** Maintainer or author
|
||||||
|
**Goal:** Selectively import or re-project valuable pages from an archived,
|
||||||
|
read-only, or retired shard into an active information space.
|
||||||
|
**Source:** federation
|
||||||
|
**Notes:** Caulfield bounded conversation / reverse bit-rot. Optional space
|
||||||
|
lifecycle policy. Complements UC-02 attach and UC-26 fork at scale.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-29 — Remix with portable attribution
|
||||||
|
|
||||||
|
**Actor:** Author
|
||||||
|
**Goal:** Reuse content across shards or spaces with attribution and edit
|
||||||
|
history intact, without manual copy-paste.
|
||||||
|
**Source:** federation, intent
|
||||||
|
**Notes:** Fedwiki journal travels with page; shard-wiki coordination journal +
|
||||||
|
per-shard history. Frictionless reuse principle (~15s not ~15min).
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-30 — Time-bounded collaboration space
|
||||||
|
|
||||||
|
**Actor:** Facilitator
|
||||||
|
**Goal:** Run a collaboration period on a dedicated information space or shard
|
||||||
|
subset, then archive it while allowing selective carry-forward.
|
||||||
|
**Source:** federation
|
||||||
|
**Notes:** Fedwiki "happening"; lifecycle is configurable policy, not a hard-
|
||||||
|
coded core behavior. Relates to UC-28.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-31 — Subscribe to remote shard changes
|
||||||
|
|
||||||
|
**Actor:** Maintainer or reader
|
||||||
|
**Goal:** Receive timely notice when pages change on attached remote shards,
|
||||||
|
triggering projection refresh or reconciliation review.
|
||||||
|
**Source:** federation, intent
|
||||||
|
**Notes:** ikiwiki pinger/pingee; ActivityPub Create/Update; polling fallback.
|
||||||
|
Transport is adapter concern; freshness surfaced in UC-24.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-32 — Transclude remote span with live freshness
|
||||||
|
|
||||||
|
**Actor:** Author or reader
|
||||||
|
**Goal:** Embed a portion of a remote page inline with visible origin and
|
||||||
|
refreshable content.
|
||||||
|
**Source:** federation, intent
|
||||||
|
**Notes:** Xanadu transclusion pattern; stronger than UC-03 whole-page
|
||||||
|
projection. Provenance and staleness must be explicit.
|
||||||
|
**Priority:** Later
|
||||||
|
|
||||||
|
### UC-33 — Git-branch an information space
|
||||||
|
|
||||||
|
**Actor:** Maintainer
|
||||||
|
**Goal:** Fork the coordination journal and attached shard configuration into a
|
||||||
|
divergent information space without destroying the original.
|
||||||
|
**Source:** federation, intent
|
||||||
|
**Notes:** ikiwiki wiki-branch pattern; Git-backed coordination per INTENT.
|
||||||
|
Space-level fork — distinct from UC-26 page-level fork.
|
||||||
**Priority:** Later
|
**Priority:** Later
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -286,15 +370,23 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
|
|||||||
|
|
||||||
## Traceability
|
## Traceability
|
||||||
|
|
||||||
| UC | c2 research | yawex research | INTENT |
|
| UC | c2 research | yawex research | federation research | INTENT |
|
||||||
|----|-------------|----------------|--------|
|
|----|-------------|----------------|---------------------|--------|
|
||||||
| UC-01 | ✓ | | ✓ |
|
| UC-01 | ✓ | | | ✓ |
|
||||||
| UC-02 | | ✓ | ✓ |
|
| UC-02 | | ✓ | | ✓ |
|
||||||
| UC-03 | | ✓ | ✓ |
|
| UC-03 | | ✓ | ✓ | ✓ |
|
||||||
| UC-04 | ✓ | ✓ | ✓ |
|
| UC-04 | ✓ | ✓ | ✓ | ✓ |
|
||||||
| UC-05 | ✓ | ✓ | ✓ |
|
| UC-05 | ✓ | ✓ | ✓ | ✓ |
|
||||||
| UC-06 | | ✓ | ✓ |
|
| UC-06 | | ✓ | | ✓ |
|
||||||
| UC-07 | | | ✓ |
|
| UC-07 | | | ✓ | ✓ |
|
||||||
|
| UC-26 | | | ✓ | ✓ |
|
||||||
|
| UC-27 | | | ✓ | ✓ |
|
||||||
|
| UC-28 | | | ✓ | |
|
||||||
|
| UC-29 | | | ✓ | ✓ |
|
||||||
|
| UC-30 | | | ✓ | |
|
||||||
|
| UC-31 | | | ✓ | ✓ |
|
||||||
|
| UC-32 | | | ✓ | ✓ |
|
||||||
|
| UC-33 | | | ✓ | ✓ |
|
||||||
| UC-08 | ✓ | | |
|
| UC-08 | ✓ | | |
|
||||||
| UC-09 | ✓ | | |
|
| UC-09 | ✓ | | |
|
||||||
| UC-10 | ✓ | | |
|
| UC-10 | ✓ | | |
|
||||||
@@ -343,6 +435,19 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
|
|||||||
| Page classes (local/global/virtual) | UC-02, UC-03 (shard roles) |
|
| Page classes (local/global/virtual) | UC-02, UC-03 (shard roles) |
|
||||||
| Wikilink / red-link semantics | UC-08, UC-23, UC-25 |
|
| Wikilink / red-link semantics | UC-08, UC-23, UC-25 |
|
||||||
|
|
||||||
|
### federation research mapping
|
||||||
|
|
||||||
|
| Research ID (findings §7) | Catalog UC |
|
||||||
|
|---------------------------|------------|
|
||||||
|
| UC-FED-01 Fork page from remote shard | UC-26 |
|
||||||
|
| UC-FED-02 View multiple versions of equivalent page | UC-27 |
|
||||||
|
| UC-FED-03 Carry forward from closed/archived shard | UC-28 |
|
||||||
|
| UC-FED-04 Remix with portable attribution | UC-29 |
|
||||||
|
| UC-FED-05 Time-bounded collaboration space | UC-30 |
|
||||||
|
| UC-FED-06 Subscribe to remote shard changes | UC-31 |
|
||||||
|
| UC-FED-07 Transclude remote span | UC-32 |
|
||||||
|
| UC-FED-08 Git-branch information space | UC-33 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Open questions
|
## Open questions
|
||||||
@@ -353,4 +458,7 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
|
|||||||
3. Do c2 collaboration patterns (UC-10, UC-14) belong in **core**, **reference
|
3. Do c2 collaboration patterns (UC-10, UC-14) belong in **core**, **reference
|
||||||
UI**, or **`wiki/` social convention** only?
|
UI**, or **`wiki/` social convention** only?
|
||||||
4. Should UC-12 and `WikiIsNotWikipedia` be elevated into
|
4. Should UC-12 and `WikiIsNotWikipedia` be elevated into
|
||||||
`ProductRequirementsDocument.md` as explicit product identity?
|
`ProductRequirementsDocument.md` as explicit product identity?
|
||||||
|
5. Which federation UCs (UC-26–UC-33) are **MVP** vs deferred until
|
||||||
|
`SHARD-WP-0002` architecture decisions land?
|
||||||
|
6. Does UC-32 (transclusion) belong in core orchestrator or adapter/UI layer?
|
||||||
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