shard-wiki/research/260614-federated-wiki-deep-dive/findings.md

# 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
  `/<slug>.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.