From f1384144eb9df2ac0f04eb062f5c419762aeced3 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 8 Jun 2026 14:55:13 +0200 Subject: [PATCH] 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. --- SCOPE.md | 11 +- research/260608-federation-concepts/README.md | 5 +- .../260608-federation-concepts/findings.md | 25 +- spec/ProductRequirementsDocument.md | 8 +- spec/UseCaseCatalog.md | 134 +++++++- .../SHARD-WP-0002-federation-architecture.md | 297 ++++++++++++++++++ 6 files changed, 446 insertions(+), 34 deletions(-) create mode 100644 workplans/SHARD-WP-0002-federation-architecture.md diff --git a/SCOPE.md b/SCOPE.md index 46713fe..ae04883 100644 --- a/SCOPE.md +++ b/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-*/`) | | Demand | NetKingdom integration asks captured, not yet negotiated | | 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) @@ -52,6 +52,9 @@ live in core. ## Current Planning -Design work is tracked in `workplans/SHARD-WP-0001-yawex-requirements.md`. -Specification outputs from that workplan land in `spec/`. Inbound integration -asks remain in `demand/` until reviewed and promoted into spec or workplans. \ No newline at end of file +Design work is tracked in `workplans/SHARD-WP-0001-yawex-requirements.md` +(yawex-derived resolution, namespaces, overlays) and +`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. \ No newline at end of file diff --git a/research/260608-federation-concepts/README.md b/research/260608-federation-concepts/README.md index bc7c114..879ccda 100644 --- a/research/260608-federation-concepts/README.md +++ b/research/260608-federation-concepts/README.md @@ -23,5 +23,6 @@ Focus: terms, architectural patterns, and **mapping to `shard-wiki` INTENT** ## Status -Initial exploration complete. Findings may inform `spec/` and future -workplans; not yet promoted to specification. \ No newline at end of file +Initial exploration complete. Use cases promoted to `spec/UseCaseCatalog.md` +(UC-26–UC-33). Federation architecture design tracked in +`workplans/SHARD-WP-0002-federation-architecture.md`. \ No newline at end of file diff --git a/research/260608-federation-concepts/findings.md b/research/260608-federation-concepts/findings.md index c142bd1..0f16ee0 100644 --- a/research/260608-federation-concepts/findings.md +++ b/research/260608-federation-concepts/findings.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 | -|----|----------|--------| -| UC-FED-01 | **Fork page from remote shard into writable shard** | Fedwiki fork; maps to overlay or import policy | -| UC-FED-02 | **View multiple versions of equivalent page** | Fedwiki chorus; union without erasure | -| UC-FED-03 | **Carry forward pages from closed/archived shard** | Bounded conversation / reverse bit-rot | -| UC-FED-04 | **Remix with portable attribution** | Fedwiki journal; coordination journal | -| UC-FED-05 | **Time-bounded collaboration space** | Happening; optional space lifecycle policy | -| UC-FED-06 | **Subscribe to remote shard changes** | ikiwiki pinger, ActivityPub Create/Update | -| UC-FED-07 | **Transclude remote span with live freshness** | Xanadu; projection + provenance | -| UC-FED-08 | **Git-branch a wiki information space** | ikiwiki branch; coordination journal fork | +| Research ID | 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 | --- diff --git a/spec/ProductRequirementsDocument.md b/spec/ProductRequirementsDocument.md index 29c976f..0f6fa4f 100644 --- a/spec/ProductRequirementsDocument.md +++ b/spec/ProductRequirementsDocument.md @@ -46,9 +46,11 @@ See `INTENT.md` § Strategic Boundaries. - `research/260608-yawex-prior-art/findings.md` — federation design seeds from 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 -Pending completion of `SHARD-WP-0001` design tasks and ratification of access -model INTENT amendments. Detailed requirements will be expanded as spec tasks -complete. \ No newline at end of file +Pending completion of `SHARD-WP-0001` and `SHARD-WP-0002` design tasks and +ratification of access model INTENT amendments. Detailed requirements will be +expanded as spec tasks complete. \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index 89b1477..a79c111 100644 --- a/spec/UseCaseCatalog.md +++ b/spec/UseCaseCatalog.md @@ -2,7 +2,8 @@ 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. ## Conventions @@ -11,7 +12,7 @@ Each use case lists: - **Actor** — who initiates the action - **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 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 reconcile them under explicit policy. **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 --- @@ -286,15 +370,23 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD. ## Traceability -| UC | c2 research | yawex research | INTENT | -|----|-------------|----------------|--------| -| UC-01 | ✓ | | ✓ | -| UC-02 | | ✓ | ✓ | -| UC-03 | | ✓ | ✓ | -| UC-04 | ✓ | ✓ | ✓ | -| UC-05 | ✓ | ✓ | ✓ | -| UC-06 | | ✓ | ✓ | -| UC-07 | | | ✓ | +| UC | c2 research | yawex research | federation research | INTENT | +|----|-------------|----------------|---------------------|--------| +| UC-01 | ✓ | | | ✓ | +| UC-02 | | ✓ | | ✓ | +| UC-03 | | ✓ | ✓ | ✓ | +| UC-04 | ✓ | ✓ | ✓ | ✓ | +| UC-05 | ✓ | ✓ | ✓ | ✓ | +| UC-06 | | ✓ | | ✓ | +| UC-07 | | | ✓ | ✓ | +| UC-26 | | | ✓ | ✓ | +| UC-27 | | | ✓ | ✓ | +| UC-28 | | | ✓ | | +| UC-29 | | | ✓ | ✓ | +| UC-30 | | | ✓ | | +| UC-31 | | | ✓ | ✓ | +| UC-32 | | | ✓ | ✓ | +| UC-33 | | | ✓ | ✓ | | UC-08 | ✓ | | | | UC-09 | ✓ | | | | 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) | | 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 @@ -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 UI**, or **`wiki/` social convention** only? 4. Should UC-12 and `WikiIsNotWikipedia` be elevated into - `ProductRequirementsDocument.md` as explicit product identity? \ No newline at end of file + `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? \ No newline at end of file diff --git a/workplans/SHARD-WP-0002-federation-architecture.md b/workplans/SHARD-WP-0002-federation-architecture.md new file mode 100644 index 0000000..67cbeac --- /dev/null +++ b/workplans/SHARD-WP-0002-federation-architecture.md @@ -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) \ No newline at end of file