diff --git a/.claude/ralph-loop.local.md b/.claude/ralph-loop.local.md new file mode 100644 index 0000000..12fb5c6 --- /dev/null +++ b/.claude/ralph-loop.local.md @@ -0,0 +1,21 @@ +--- +active: true +iteration: 1 +session_id: b24b53ca-a25b-4a18-8331-925c4100d39f +max_iterations: 20 +completion_promise: "HEUREKA" +workplan_id: SHARD-WP-0003 +workplan_file: workplans/SHARD-WP-0003-engine-dives-batch.md +started_at: "2026-06-14T16:37:36Z" +--- + +Read the workplan at `workplans/SHARD-WP-0003-engine-dives-batch.md`. + +If every task has `status: done` AND frontmatter `status: done`: +run `rm -f .claude/ralph-loop.local.md` first (deactivates the loop so the stop hook exits cleanly), +then output HEUREKA. + +Otherwise implement the next `todo` task as described in the workplan. +Set task `in_progress` when starting, `done` when complete. +When all tasks are done set frontmatter `status: done`. + diff --git a/SCOPE.md b/SCOPE.md index 1f3d399..a99b8d8 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -19,9 +19,9 @@ Learnings update both SCOPE and INTENT where necessary. |-------|-------| | Code | Python package scaffold (`src/shard_wiki/`, smoke tests only) | | Intent | `INTENT.md` established; authorization-in-core amendments drafted | -| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js deep dives & shard-spectrum synthesis (`research/260614-*/`) | +| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq + local-first workspaces (Anytype/AFFiNE/AppFlowy) + Trilium + Wiki.js + Federated Wiki deep dives & shard-spectrum synthesis (`research/260614-*/`) | | Demand | NetKingdom integration asks captured, not yet negotiated | -| Spec | Architecture blueprint drafted; UseCaseCatalog 69 UCs from research; PRD/TSD scaffolds | +| Spec | Architecture blueprint drafted; UseCaseCatalog 72 UCs from research; PRD/TSD scaffolds | | Work | `SHARD-WP-0001` active (6 tasks); `SHARD-WP-0002` active (16 tasks: T1–T10 federation + T11–T16 adapter contract); `SHARD-WP-0003` active (9 engine dives); `SHARD-WP-0004` active (8 computational-knowledge dives) | ## In Scope (today) diff --git a/research/260614-federated-wiki-deep-dive/README.md b/research/260614-federated-wiki-deep-dive/README.md new file mode 100644 index 0000000..bf5517b --- /dev/null +++ b/research/260614-federated-wiki-deep-dive/README.md @@ -0,0 +1,20 @@ +# 260614 — Federated Wiki deep dive + +Deep dive on Ward Cunningham's **Federated Wiki** (Smallest Federated Wiki / SFW, +2011 →) as a **federation model** rather than a single shard: fork-with-provenance, +the per-page **JSON journal** of semantic actions, the **story** of typed items, the +**neighborhood/roster** discovery model, and time-bounded **happenings**. + +This is prior art for shard-wiki's **coordination layer itself** — the closest existing +system to "a union of pages preserving provenance, assembled non-destructively." It +extends `research/260608-federation-concepts/` §3 with the concrete data model + protocol. + +- `findings.md` — full writeup: data model, journal/action types, federation protocol, + capability profile, INTENT mapping, UC seeds (UC-70–UC-72), architecture notes for + SHARD-WP-0002, open questions, sources, traceability. + +Catalog yield: UC-70 (attach a fedwiki site via page-JSON + CORS), UC-71 (append-only +semantic action journal with site provenance as a coordination-journal model), UC-72 +(fork-with-site-provenance federation across a neighborhood / chorus). Enriched +UC-26/28/30/05/27. Feeds SHARD-WP-0002 T1–T5 (federation) and T11/T13/T16 (write +granularity, log-based merge, identity≠placement). diff --git a/research/260614-federated-wiki-deep-dive/findings.md b/research/260614-federated-wiki-deep-dive/findings.md new file mode 100644 index 0000000..cbeb9b3 --- /dev/null +++ b/research/260614-federated-wiki-deep-dive/findings.md @@ -0,0 +1,240 @@ +# Federated Wiki — deep dive (findings) + +**Date:** 2026-06-14 · **Source:** SHARD-WP-0003 T1 · **Subject:** Ward Cunningham's +Smallest Federated Wiki (SFW) / Federated Wiki (fedwiki ecosystem). + +## Why this dive + +Every prior dive has been a *shard candidate* — a store we might attach. Federated Wiki +is different: it is a **federation model**, the one piece of public prior art whose core +job is the same as shard-wiki's coordination layer — *present a union of pages from many +independent sites while preserving where each came from, and let people copy and edit +non-destructively*. Ward Cunningham (inventor of the wiki) built SFW in 2011 precisely to +fix the original wiki's single-canonical-page weakness with **fork + provenance**. We go +past the surface (`260608-federation-concepts/` §3) into the data model and protocol, then +ask what shard-wiki should adopt. + +**Framing:** fedwiki is not just "a shard we attach" — it is a *worked example of the +coordination journal, overlay-before-mutation, and union-without-erasure*, three of our +own design pillars, shipped and running. + +--- + +## 1. The data model — page = title + story + journal + +A fedwiki page is a small JSON object with three core fields (plus optional decoration): + +```json +{ + "title": "Welcome Visitors", + "story": [ + { "type": "paragraph", "id": "7b56f22a4b9ee974", + "text": "Welcome to this [[Federated Wiki]] site." }, + { "type": "image", "id": "a1c0e3...", "url": "...", "caption": "..." } + ], + "journal": [ + { "type": "create", "id": "7b56f22a4b9ee974", "item": {...}, "date": 1310000000000 }, + { "type": "add", "id": "a1c0e3...", "item": {...}, "after": "7b56f22a4b9ee974", + "date": 1310000100000 }, + { "type": "edit", "id": "7b56f22a4b9ee974", "item": {...}, "date": 1310000200000 }, + { "type": "fork", "site": "ward.fed.wiki.org", "date": 1310000300000 } + ] +} +``` + +- **story** — an *ordered array of typed items* ("paragraph-like" items). Each item is + `{ type, id, text, ...type-specific }`. The **`id`** is a random 16-hex string, + **stable across edits** (it is the unit of identity within a page). The **`type`** names + the **plugin** that renders/edits the item (`paragraph`, `image`, `html`, `markdown`, + `code`, `method`, `pagefold`, chart plugins, …). *Data lives in the item; behavior lives + in the plugin* — the item is portable JSON; the plugin is the renderer. +- **journal** — an *ordered, append-only array of action objects* that, when replayed, + **reconstructs the story**. The story is a materialized view of the journal. This is the + key architectural choice: **the journal is the source of truth, the story is derived.** + +## 2. Journal action types — a semantic op-log + +Each journal entry is an action with `{ type, ... , date }` (epoch-ms). The action types: + +| action | fields | meaning | +|---------|--------|---------| +| `create`| `id, item, date` | first item — page born | +| `add` | `id, item, after, date` | insert an item after another | +| `edit` | `id, item, date` | replace an item's content (id preserved) | +| `move` | `order, date` | reorder items | +| `remove`| `id, date` | delete an item | +| `fork` | `site, date` | **mark that the page was copied from `site` at this point** | + +Two things matter for us: + +1. **These are *semantic* operations** (add/move/edit/remove a paragraph), not text diffs + and not character-level CRDT ops. The write granularity is the **story item + (paragraph)** — a *middle* granularity between whole-file (TiddlyWiki) and + block/character (Logseq/CRDT). It is an **op-log** like a CRDT, but the ops are + coarse-grained and **applied by humans via fork**, not auto-merged. +2. **`fork` is the provenance primitive.** When you copy a remote page to your own site, + a `fork` entry is appended recording the **source site** and time. The journal of a + forked page therefore **serializes a directed acyclic graph (DAG)** of where content + came from — "the journal of a forked page is detailed enough to recognize where in the + journal of the original the fork took place" (CouchDB-style per-entry sequence numbers + make the cut-point identifiable). History visualization highlights the forked entry. + +## 3. The federation protocol — sites, neighborhood, roster + +- **Site** = an independent server (originally Node.js; also static-file and serverless + variants). A site owns a set of pages, each served as **page JSON over HTTP** at + `/.json`, with **CORS headers** so a *browser-side* client can fetch pages from + **any** site. Page identity within a site is the **slug** (a title-derived kebab name). +- **The client assembles the union, not the server.** The fedwiki client ("the lineup") + renders pages **side by side**: clicking a link opens that page *from whatever site it + resolves against*, appended to the right. Browsing literally builds a left-to-right + trail across sites. +- **Neighborhood** = the dynamic set of sites encountered in the current session (from the + sites of pages you've opened, links, and forks). **Search runs across the neighborhood** + — a federated search over exactly the sites you've touched. +- **Roster** = an explicit, authored list of sites to include (a curated neighborhood); + "sister sites" are peers you watch. There is **no central registry** — discovery is by + link, fork, and roster. +- **Happenings** = time-bounded collaborative events where many participants fork around a + topic for a period, producing a burst of related forks (a bounded collaboration that + leaves a durable forked record on each participant's own site). + +## 4. The editorial model — fork, don't edit-in-place + +You can only write to **your own** site. To change someone else's page you **fork** it +(copy into your site, journal records the source), then edit your copy. Many forks of the +same page coexist across sites — Cunningham's **"chorus of voices"**: *no canonical +version*, divergence is normal and visible, and you choose whose changes to pull by forking +them. There is **no automatic merge** — reconciliation is human: compare journals, fork the +version you prefer, optionally re-fork upstream changes. + +--- + +## 5. Capability profile + +| Dimension (synthesis spectrum) | Federated Wiki | +|--------------------------------|----------------| +| Attachment mode | **REST/file-store hybrid** — page JSON over HTTP+CORS; also static files | +| Addressing granularity | **story item (paragraph)** via stable 16-hex `id` | +| Content identity | item `id` random+stable; page id = site + slug | +| Identity vs placement | **placement-bound**: identity = `site` + `slug`; forks are *new* identities linked by journal provenance | +| Structure | ordered array of **typed items** (plugin-typed) | +| History | **per-page append-only journal** of semantic actions (op-log) | +| Merge model | **fork + manual journal compare** — a *third model* beside git 3-way and CRDT auto-merge | +| Native query | none built-in; **neighborhood search** (federated full-text across touched sites) | +| Translation | item `text` is wiki/Markdown-ish; plugins own their formats | +| Attachment/write granularity | **story-item level** (add/edit/move/remove one item) | +| Operational envelope | tiny servers, browser-driven; CORS is the whole API surface | +| Access grant | **own-site-only writes**; reads open via CORS | +| Content opacity | transparent JSON (no E2EE); plugin-typed but inspectable | +| Provenance | **first-class** — `fork` records source site; journal = provenance DAG | + +## 6. INTENT mapping + +### Reinforcements (fedwiki validates our pillars) + +- **Coordination journal** (INTENT) ≈ fedwiki **journal**. Our journal idea is *exactly* + fedwiki's per-page append-only action log — and fedwiki proves the story-as-derived-view + pattern works. Strong reinforcement; adopt the **semantic-op + provenance-entry** shape. +- **Overlay before mutation** ≈ **fork**. Fork *is* the canonical overlay: a + non-destructive copy onto a writable surface, recording provenance, before any change. +- **Union without erasure** ≈ **neighborhood + chorus**. The union is assembled from many + sovereign sites; provenance (which site, forked-from) is never hidden; divergence is + surfaced, not resolved away. +- **No silent remote mutation** ≈ **own-site-only writes**. You structurally *cannot* + mutate a remote; you fork to your own site. This is our rule, enforced by architecture. +- **Mechanism over policy** ≈ **no canonical source**. Fedwiki ships the mechanism (fork, + journal, neighborhood) and leaves "which version wins" entirely to people. +- **Graceful degradation** ≈ static-file sites — a fedwiki site can be a read-only pile of + JSON files; still forkable, still in the neighborhood. + +### Divergences (boundaries / design notes, not bugs) + +- **Identity = placement.** Fedwiki page identity is `site` + `slug`; a fork is a *new* + page whose only tie to the origin is a journal `fork` entry. shard-wiki wants + **identity ≠ placement** (the "same" page across shards under a stable identity, T16) — + so we treat fedwiki's journal-linked forks as *provenance edges*, and layer our own + cross-shard identity over them rather than adopting slug-as-identity. +- **No query / no typed-record model.** Fedwiki is paragraphs+plugins, not a typed DB + (contrast Notion/Wikibase). Fine — it sits at the *coordination* end, not the structure + end. We don't ask fedwiki to provide query; the neighborhood search is the model for + *federated* search across shards (T-federation), not in-shard query. +- **Browser-assembles-union.** Fedwiki pushes union assembly to the client. shard-wiki + assembles server/orchestrator-side. Adopt the *model* (union from sovereign sources + + provenance), not the client-only locus. + +### What to keep + +1. **Journal = append-only semantic-op log with provenance entries**, story = derived + replay view. This is the concrete shape for our coordination journal (T13). +2. **Fork-with-source-attribution** as the overlay/adopt primitive across shards. +3. **Neighborhood** as the model for a *dynamic, link-and-fork-discovered* federated set + + search, with **roster** as the curated/explicit variant. +4. **Chorus of forks** — represent divergent versions across shards as co-equal, linked by + provenance, with reconciliation as an explicit human/policy step (mechanism over policy). + +--- + +## 7. UC seeds + +| # | Seed | Disposition | +|---|------|-------------| +| UC-70 | Attach a Federated Wiki site as a shard via its **page JSON + CORS** (REST/file-store hybrid); project pages, fork to overlay | **new** | +| UC-71 | Adopt a **per-page append-only semantic-action journal with provenance entries** (fork=source site) as the coordination-journal model — replay to materialize, compare to locate divergence | **new** | +| UC-72 | **Fork-with-site-provenance federation across a neighborhood** of peer shards — assemble a union from links/forks, search across it, preserve the chorus without forcing a canonical | **new** | +| — | fork-with-provenance as overlay/adopt | enrich **UC-26** (fork) | +| — | carry-forward of forked content + upstream re-fork | enrich **UC-28** (carry-forward) | +| — | happenings = time-bounded collaboration leaving durable forks | enrich **UC-30** (time-bounded space) | +| — | union/chorus of co-equal versions, provenance-linked | enrich **UC-05 / UC-27** | + +## 8. Architecture notes for SHARD-WP-0002 + +- **T1–T5 (federation):** fedwiki is the reference design. The **journal** (append-only, + semantic ops, fork-provenance) is the concrete coordination-journal shape; **neighborhood + + roster** is the discovery/membership model (dynamic vs curated); **fork** is the + overlay/adopt op. Model the union as an assembly over sovereign sources with provenance + edges, reconciliation left to policy. +- **T11 (capability/write-granularity):** add **story-item / paragraph** as a named + write-granularity tier between whole-file and block/character. +- **T13 (history portability / merge model):** record fedwiki's **journal-replay op-log** + as a *third merge model* beside git 3-way and CRDT auto-merge — a **coarse semantic + op-log applied manually via fork**. A shard whose history *is* such a journal can supply + our coordination journal almost directly (vs git-commit import or CRDT-update import). +- **T16 (identity ≠ placement):** fedwiki's `fork` journal entries are **provenance edges** + between same-named pages on different sites — exactly the cross-shard "same page, + different placement" relation we must model. Use them as edges; keep our own identity + layer above slug. + +## 9. Open questions + +1. Should shard-wiki's coordination journal adopt fedwiki's **exact action vocabulary** + (create/add/edit/move/remove/fork) at the page-item level, or a more granular/abstract + op set that other shards can also emit? +2. Is **neighborhood** (dynamic, link/fork-discovered) a first-class membership mode for an + information space, or only a *view* over an explicitly-configured shard set (roster)? +3. How do we reconcile fedwiki's **slug-as-identity + fork-DAG** with our intended + **stable cross-shard identity** (T16) — promote fork edges into the identity graph, or + keep them as provenance-only annotations? +4. Does the **chorus / no-canonical** stance compose with shards that *do* assert a + canonical (Notion, an upstream git main)? (policy-selectable canonical over a + mechanism that permits chorus.) + +## 10. Sources + +- Smallest Federated Wiki wiki: **Story JSON**, **Federation Details** — + github.com/WardCunningham/Smallest-Federated-Wiki/wiki +- JSON Schema notes — song.fed.wiki.org/json-schema.html +- "Smallest Federated Wiki" — home.c2.com/smallest-federated-wiki.html +- Federated Wiki — federated.wiki (Visualizing Page History) +- Mike Caulfield, "The OER Case for Federated Wiki" — hapgood.us (2015) +- Jon Udell, "A federated Wikipedia" — blog.jonudell.net (2015) +- Wikipedia: *Federated Wiki*; IndieWeb: *Smallest Federated Wiki* +- fedwiki/wiki-plugin-transport (plugin/transport reference) +- prior: `research/260608-federation-concepts/` §3 + +## 11. Traceability + +New UCs **UC-70–UC-72** carry the marker **⊞** in the wikiengines column of +`spec/UseCaseCatalog.md` (true lineage = this dive; placed in the nearest existing column). +Enriched: UC-26, UC-28, UC-30, UC-05, UC-27. Architecture cross-refs: SHARD-WP-0002 +T1–T5, T11, T13, T16. diff --git a/research/README.md b/research/README.md index cf67dad..9b5ca7a 100644 --- a/research/README.md +++ b/research/README.md @@ -27,4 +27,5 @@ when multiple files or sources are involved. Findings here inform `spec/` and | 2026-06-14 | `260614-logseq-deep-dive/` | Logseq — block-graph on plain Markdown files, in-file block IDs, derived Datalog index; UC-62/63 | | 2026-06-14 | `260614-localfirst-workspaces-deep-dive/` | Anytype · AFFiNE · AppFlowy — CRDT local-first workspaces (any-sync/Yjs/Yrs), native merge, P2P/E2EE; UC-64/65 | | 2026-06-14 | `260614-trilium-deep-dive/` | Trilium/TriliumNext — note cloning (DAG hierarchy), attribute inheritance/templates, HTML-native, scripting+ETAPI; UC-66/67 | -| 2026-06-14 | `260614-wikijs-deep-dive/` | Wiki.js — storage-module engine (DB↔Git Markdown), GraphQL API, pluggable modules ≈ adapter-contract prior art; UC-68/69 | \ No newline at end of file +| 2026-06-14 | `260614-wikijs-deep-dive/` | Wiki.js — storage-module engine (DB↔Git Markdown), GraphQL API, pluggable modules ≈ adapter-contract prior art; UC-68/69 | +| 2026-06-14 | `260614-federated-wiki-deep-dive/` | Federated Wiki — fork-with-provenance, per-page semantic-action journal (story=replay), neighborhood/roster + chorus; prior art for our coordination journal / overlay / union pillars; UC-70/71/72 | \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index af941cf..c879f36 100644 --- a/spec/UseCaseCatalog.md +++ b/spec/UseCaseCatalog.md @@ -11,7 +11,8 @@ Promoted from `research/260608-c2-wiki-origins/`, `research/260614-notion-deep-dive/`, `research/260614-joplin-deep-dive/`, `research/260614-logseq-deep-dive/`, `research/260614-localfirst-workspaces-deep-dive/`, -`research/260614-trilium-deep-dive/`, and `research/260614-wikijs-deep-dive/`. +`research/260614-trilium-deep-dive/`, `research/260614-wikijs-deep-dive/`, and +`research/260614-federated-wiki-deep-dive/`. See InfoTechPrimers on coulomb.social for use-case catalog conventions. ## Conventions @@ -121,7 +122,11 @@ 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`. Should record a **created-from genealogy edge** in the coordination journal so the lineage is navigable as a dimension (UC-49, -`research/260614-zigzag-deep-dive/findings.md` §9). +`research/260614-zigzag-deep-dive/findings.md` §9). The fedwiki deep dive details the +concrete shape: fork is **own-site-only write + a `fork` journal entry recording the source +site**, and a forked journal stays **detailed enough to locate the upstream cut-point** +(`research/260614-federated-wiki-deep-dive/findings.md` §2, §4) — enabling later +carry-forward/re-fork (UC-28) and modelling the genealogy edge as **provenance** (UC-71/72). **Priority:** Later ### UC-27 — View multiple versions of equivalent page @@ -910,6 +915,58 @@ sub-mode beside Notion's REST. --- +### UC-70 — Attach a Federated Wiki site as a shard (page JSON + CORS) + +**Actor:** Orchestrator / adapter +**Goal:** Attach a **Federated Wiki** site as a shard via its **page JSON** served over +**HTTP with CORS** (`/.json`); project its pages and **fork** them to overlay +non-destructively. +**Source:** federation, intent +**Notes:** A fedwiki site is a sovereign server (Node.js, static-file, or serverless) +serving `{ title, story[], journal[] }` page JSON +(`research/260614-federated-wiki-deep-dive/findings.md` §1, §3). A **REST/file-store +hybrid** attachment mode: CORS-readable JSON over HTTP, or a static pile of `.json` files. +Writes are **own-site-only** — to change a remote page you **fork** it (UC-26), so this +shard is naturally a read/project + overlay target, never silent remote mutation. Feeds +SHARD-WP-0002 T14 (attachment mode), T11 (capability profile). +**Priority:** Later + +### UC-71 — Coordination journal as an append-only semantic-action log with provenance + +**Actor:** Core orchestrator +**Goal:** Model the coordination journal as a **per-page append-only log of semantic +actions** (`create`/`add`/`edit`/`move`/`remove`/`fork`) carrying **provenance entries** +(fork records the source site), with the page state **derived by replaying** the log and +divergence **located by comparing** logs. +**Source:** federation, intent +**Notes:** Directly adopts the fedwiki **journal** shape — the story is a materialized +view of the journal, fork entries serialize a **provenance DAG**, and per-entry sequence +numbers make the fork cut-point identifiable +(`research/260614-federated-wiki-deep-dive/findings.md` §2, §6). This is concrete prior art +for INTENT's coordination journal: a **third merge model** beside git 3-way and CRDT +auto-merge — a coarse semantic op-log applied manually via fork. Feeds SHARD-WP-0002 T13 +(history portability / merge model) and T1–T5 (federation). +**Priority:** Later + +### UC-72 — Federate by fork-with-provenance across a neighborhood / chorus + +**Actor:** Reader / curator +**Goal:** Assemble a **union from sovereign peer shards** discovered by **link and fork** +(a *neighborhood*) or by an explicit **roster**, **search across that set**, and preserve a +**chorus of co-equal, provenance-linked versions** without forcing a canonical — pulling +another's changes by forking them. +**Source:** federation, intent +**Notes:** Fedwiki's neighborhood (dynamic, link/fork-discovered) vs roster (curated) +membership and "chorus of voices" no-canonical stance +(`research/260614-federated-wiki-deep-dive/findings.md` §3, §4) model +**union-without-erasure** at the coordination layer: divergence is normal and visible, +reconciliation is an explicit human/policy step (mechanism over policy). Open: does a +chorus compose with shards that assert a canonical? Feeds SHARD-WP-0002 T1–T5; relates +UC-05/UC-27 (union/chorus), UC-26 (fork). +**Priority:** Later + +--- + ## B. Knowledge work and collaboration *Patterns from c2 social conventions and yawex authoring workflows.* @@ -1170,6 +1227,9 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD. | UC-67 | | | | ⊕ | ✓ | | UC-68 | | | | ⚓ | ✓ | | UC-69 | | | | ⚓ | ✓ | +| UC-70 | | | ✓⊞ | | ✓ | +| UC-71 | | | ✓⊞ | | ✓ | +| UC-72 | | | ✓⊞ | | ✓ | | UC-08 | ✓ | | | | UC-09 | ✓ | | | | UC-10 | ✓ | | | @@ -1578,6 +1638,38 @@ layer. Architecture logged for `SHARD-WP-0002` (T11/T14): storage-module abstrac second adapter-contract prior art, engine-maintained Git mirror as attach+write surface, GraphQL introspection for capability discovery + selective projection. +### federated-wiki mapping + +(⊞ UC-70–UC-72 are placed in the **federation** matrix column — Federated Wiki was first +surfaced in `research/260608-federation-concepts/` — but their deepened lineage is the +**Federated Wiki deep dive**, `research/260614-federated-wiki-deep-dive/findings.md`.) + +| Federated Wiki mechanism (findings §) | Catalog UC | +|---------------------------------------|------------| +| Page JSON `{title, story[], journal[]}` over HTTP+CORS; static-file sites (§1, §3) | UC-70 (new) | +| Per-page append-only **journal** of semantic actions; story = derived replay; `fork` = provenance entry (§1, §2) | UC-71 (new) | +| **Neighborhood** (link/fork-discovered) + **roster** (curated) + chorus of forks (§3, §4) | UC-72 (new) | +| **fork** = non-destructive copy with source-site attribution (§2, §4) | UC-26 (enriched) | +| Forked journal carries upstream cut-point → carry-forward + re-fork (§2) | UC-28 (enriched) | +| **Happenings** = time-bounded collaboration leaving durable forks (§3) | UC-30 (enriched) | +| Chorus of co-equal, provenance-linked versions; no canonical (§4) | UC-05 / UC-27 (enriched) | +| Story-item (paragraph) write granularity; stable 16-hex item `id` (§1, §5) | links UC-35 | +| Journal-replay op-log = third merge model (vs git 3-way, CRDT) (§5, §8) | links UC-36 / UC-64 | + +Note: Federated Wiki is the one studied system whose *core job is shard-wiki's own* — a +**union of pages from sovereign sites preserving provenance, assembled non-destructively**. +It is therefore prior art not for a *shard* but for three of our **pillars**: the +**coordination journal** (its per-page append-only **journal** of semantic actions, with +the **story** as a derived replay view, UC-71), **overlay-before-mutation** (its **fork** — +own-site-only writes, source-site attribution, UC-26), and **union-without-erasure** (its +**neighborhood/roster** membership and **chorus** of provenance-linked forks, UC-72). As a +shard it attaches as a **REST/file-store hybrid** (page JSON + CORS, UC-70). **Boundary +recorded:** adopt the *model* (journal shape, fork-with-provenance, neighborhood) not the +client-only union-assembly locus or slug-as-identity; layer our cross-shard identity (T16) +above fedwiki's fork-DAG provenance edges. Architecture logged for `SHARD-WP-0002` +(T1–T5, T11, T13, T16): journal-as-coordination-journal, story-item write granularity, +journal-replay as a third merge model, fork entries as identity≠placement provenance edges. + --- ## Open questions @@ -1630,5 +1722,9 @@ GraphQL introspection for capability discovery + selective projection. live from the shard's tree/templates, and how is per-attribute provenance recorded? 22. For an **engine-maintained Git mirror** (UC-68), is the mirror or the engine DB the source of truth, and how do we write-by-commit without racing the engine's own sync? +23. Should the **coordination journal** (UC-71) adopt fedwiki's exact semantic-action + vocabulary (create/add/edit/move/remove/fork) at item granularity, or an abstract op + set other shards can also emit — and does a **chorus / no-canonical** union (UC-72) + compose with shards that assert a canonical? (Federated Wiki dive §9.) 23. How does shard-wiki **honor/surface a shard's path-based access rules** (UC-06) in a projection without re-implementing its ACL engine? (Wiki.js dive §9.) \ No newline at end of file