generated from coulomb/repo-seed
research: shard-spectrum synthesis v3 (folds SHARD-WP-0003 batch)
Extends the capability model to the nine WP-0003 engines (~23 systems total). Per-shard spectra 13 -> 14 (adds provenance granularity); refines merge-model (+fork/journal-replay, +coexist-with-rank), attachment-mode (+git-IS-store, +container, +direct-DB, +REST/file-store-hybrid, +external-API payload-format facet), native-query (+SPARQL/RDF far-end), history (+DB-rows, +partial), structure (+typed-graph, +inline-embedded objects), content-opacity (+lossy-exportable), write-granularity (+story-item, +section-anchor). Headline: new federation-model taxonomy (S2.5) -- federation is plural (fork+journal / VCS-replication+ping / query-time graph join / feed aggregation / activity streams / engine-mirror), a selectable/composable coordination-layer axis feeding SHARD-WP-0002 T1-T6. Folds UC-68-82 into the workplan; no new UCs, no INTENT boundary change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -1,21 +0,0 @@
|
||||
---
|
||||
active: true
|
||||
iteration: 2
|
||||
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 <promise>HEUREKA</promise>.
|
||||
|
||||
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`.
|
||||
|
||||
@@ -1,55 +1,69 @@
|
||||
# 260614 — Shard spectrum synthesis (one capability model across the full dive set)
|
||||
|
||||
Date: 2026-06-14 · **revised 2026-06-14 (v2)**
|
||||
Date: 2026-06-14 · **revised 2026-06-14 (v3)**
|
||||
|
||||
## What this is
|
||||
|
||||
A **synthesis** (no new external research) that reads every studied system *across* the
|
||||
others and distills them into a single comparative model feeding the **shard adapter
|
||||
contract** (`SHARD-WP-0002`).
|
||||
contract** and the **federation track** (`SHARD-WP-0002`).
|
||||
|
||||
**v2** extends from nine systems to the full set and grows the spectra from eleven to
|
||||
**thirteen**. The systems: two conceptual ancestors (**Xanadu, ZigZag**), four engines
|
||||
(**XWiki, TWiki, Foswiki** + the wiki-engines landscape), and the modern note/PKB tools
|
||||
(**Roam, Obsidian, Notion, Joplin, Logseq, Anytype, AFFiNE, AppFlowy, Trilium**), against
|
||||
the federation/origin research.
|
||||
**v3** extends the model to the **SHARD-WP-0003 engine batch** (Federated Wiki, Wikibase/
|
||||
Wikidata, the git-forge wikis Gitea/GitLab/GitHub, TiddlyWiki, ikiwiki, Salesforce Quip,
|
||||
MojoMojo, Oddmuse, UseModWiki) — ~23 systems in all. Per-shard spectra grow from thirteen to
|
||||
**fourteen** (adds **provenance granularity**), and a **new coordination-layer axis** is
|
||||
introduced: the **federation-model taxonomy**.
|
||||
|
||||
Centerpieces:
|
||||
- **The shard family matrix** — every candidate backend × {substrate, attach mode(s),
|
||||
addressing, structure, history, **merge**, query, →Markdown, **opacity**}, with Xanadu/
|
||||
ZigZag as the ideal anchors.
|
||||
- **The thirteen capability spectra** — the claim that the adapter contract should model
|
||||
*positions on spectra*, each anchored at both ends by a real system, with federation
|
||||
ops degrading by position. v2 adds **content opacity** (12th) and **merge model**
|
||||
(13th), plus emphasis on **identity vs placement**, and expands the attachment-mode
|
||||
spectrum (file-store native/interchange-mirror, in-engine-host, local-REST,
|
||||
external-API, CRDT-replica, P2P/no-central-endpoint).
|
||||
- **UC-44–UC-67 → workplan task mapping** (T11–T16).
|
||||
addressing, structure, history, merge, query, →Markdown, opacity}, with Xanadu/ZigZag as
|
||||
ideal anchors and Federated Wiki as the federation-model anchor. v3 adds the flat-file
|
||||
floor (Oddmuse/UseModWiki), git-IS-store (forge wikis/ikiwiki), TiddlyWiki, MojoMojo
|
||||
(direct-DB), Quip (external-API/HTML), and Wikibase (typed-graph far-end).
|
||||
- **The fourteen capability spectra** — the claim that the adapter contract should model
|
||||
*positions on spectra*, each anchored at both ends by a real system, with federation ops
|
||||
degrading by position. v3 adds **provenance granularity** (14th: per-shard → per-page →
|
||||
per-edit → per-statement/value), and refines merge-model (+fork/journal-replay,
|
||||
+coexist-with-rank), attachment-mode (+git-IS-store, +container, +direct-DB,
|
||||
+REST/file-store-hybrid, +external-API payload-format facet), native-query (+SPARQL/RDF
|
||||
far-end, +filter mid), history (+DB-version-rows, +partial/truncated), structure
|
||||
(+typed-graph, +inline-embedded objects), content-opacity (+proprietary-lossy-exportable),
|
||||
write-granularity (+story-item, +section-anchor).
|
||||
- **The federation-model taxonomy (§2.5, new)** — federation itself is plural: fork+journal
|
||||
(Federated Wiki), VCS-replication+ping (ikiwiki), query-time graph join (Wikibase SPARQL
|
||||
`SERVICE`), feed aggregation, activity streams, engine-mirror (Wiki.js). A
|
||||
selectable/composable coordination-layer axis feeding **T1–T6**.
|
||||
- **UC-44–UC-82 → workplan task mapping** (T1–T6 + T11–T16).
|
||||
|
||||
## Contents
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `findings.md` | Family matrix, the thirteen spectra, cross-cutting through-lines, UC→task fold-in, recommendations/decisions, escalated open questions |
|
||||
| `findings.md` | Family matrix, the fourteen spectra, the federation-model taxonomy, cross-cutting through-lines, UC→task fold-in, recommendations/decisions, escalated open questions |
|
||||
|
||||
## Status
|
||||
|
||||
Synthesis v2 complete. No new use cases (consolidation only). Feeds `SHARD-WP-0002`: T11
|
||||
reframed around the **thirteen spectra** (incl. content-opacity + merge-model); T12
|
||||
page-model breadth (prose + typed/**computed** records + non-Markdown assets +
|
||||
query-defined + **multi-placement/DAG identity**); T13 history (incl. CRDT-log =
|
||||
supplement); T14 **full attachment-mode taxonomy** (CRDT-replica + P2P + interchange-mirror
|
||||
+ local-REST added); T15 lossy-with-fidelity-report (incl. HTML); T16 (addressing, content
|
||||
identity, **identity≠placement**, derived index, dimensional/query). UC coverage extended
|
||||
UC-34–UC-59 → **UC-34–UC-67**.
|
||||
Synthesis v3 complete. No new use cases (consolidation only). Feeds `SHARD-WP-0002`:
|
||||
**T1–T6** federation-model taxonomy (selectable/composable federation); **T11** reframed
|
||||
around the **fourteen spectra** (incl. provenance granularity + expanded attachment modes +
|
||||
external-API payload-format facet); T12 page-model breadth (prose + typed/computed records +
|
||||
**inline-embedded objects** + **typed-graph statements** + non-Markdown assets +
|
||||
query-defined + multi-placement/DAG identity); T13 history (DB-rows + partial-flat-file =
|
||||
supplement; completeness metadata; **journal-shaped** coordination journal); T14 **full
|
||||
attachment taxonomy** (git-IS-store / container / direct-DB / REST-file-hybrid +
|
||||
source-of-truth per binding); T15 lossy + **not-Markdown** (graph/HTML); T16 (addressing
|
||||
incl. statement GUID + **opaque stable identity**, identity≠placement, derived index,
|
||||
**graph query / federated SERVICE**). UC coverage extended UC-34–UC-67 → **UC-34–UC-82**.
|
||||
|
||||
**New through-lines (v2):** CRDT changes the merge math (native merge — never impose git
|
||||
merge); identity ≠ placement (Trilium note/branch) is the model for multi-location/
|
||||
multi-shard pages; metadata can be computed (inherited/templated), not just stored;
|
||||
content opacity is per-item, not only whole-shard; the attach surface is not always the
|
||||
native store (Joplin sync mirror; Logseq file-vs-DB and its substrate migration); the
|
||||
block-graph-on-files sweet spot (Logseq `id::`) resolves the addressing tension.
|
||||
**New through-lines (v3):** federation is plural (the federation-model taxonomy); provenance
|
||||
has a granularity spectrum (down to per-statement, Wikibase rank/references); git is both the
|
||||
home store and the home journal (forge wikis make git *the* store, resolving the engine-
|
||||
mirror write-race); the flat-file floor (Oddmuse/UseModWiki, Wikipedia's MediaWiki Phase I)
|
||||
is the field's common root and the minimal capability profile; the page model must also carry
|
||||
typed-graph statements and inline-embedded objects.
|
||||
**Carried from v2:** CRDT changes the merge math; identity ≠ placement; metadata can be
|
||||
computed; content opacity is per-item; the attach surface is not always the native store; the
|
||||
block-graph-on-files sweet spot (Logseq `id::`).
|
||||
**Carried from v1:** files-canonical/index-derived; fine-grained addressing is adoptable;
|
||||
transclusion=clone=embed is one primitive; structure/history federate iff in-text; attach
|
||||
mode is per-binding; Notion proves the platform can enforce no-silent-mutation.
|
||||
</content>
|
||||
transclusion=clone=embed=reference is one primitive; structure/history federate iff in-text;
|
||||
attach mode is per-binding; the platform can enforce no-silent-mutation.
|
||||
|
||||
@@ -1,26 +1,31 @@
|
||||
# Synthesis — the shard spectrum: one capability model across the full dive set
|
||||
|
||||
Date: 2026-06-14 · **revised 2026-06-14 (v2)** — extended from nine systems to the full
|
||||
set (added Joplin, Logseq, the CRDT local-first cohort — Anytype/AFFiNE/AppFlowy — and
|
||||
Trilium); spectra grown from eleven to **thirteen**.
|
||||
Date: 2026-06-14 · **revised 2026-06-14 (v3)** — extended from the fourteen-system set to
|
||||
include the **SHARD-WP-0003 engine batch** (Federated Wiki, Wikibase/Wikidata, the git-forge
|
||||
wikis Gitea/GitLab/GitHub, TiddlyWiki, ikiwiki, Salesforce Quip, MojoMojo, Oddmuse,
|
||||
UseModWiki). Per-shard spectra grown from thirteen to **fourteen** (added **provenance
|
||||
granularity**), with refinements to merge-model, attachment-mode, native-query, structure,
|
||||
history, content-opacity and write-granularity; and a **new coordination-layer axis — the
|
||||
federation-model taxonomy (§2.5)** — the headline v3 contribution.
|
||||
Source kind: **synthesis** — consolidates every deep dive into a single comparative model
|
||||
feeding the **shard adapter contract** (`SHARD-WP-0002` T11–T16)
|
||||
feeding the **shard adapter contract** and the **federation track** (`SHARD-WP-0002`).
|
||||
Lens: shard-wiki — what a backend must expose to participate, expressed as *spectra* of
|
||||
capability rather than a yes/no checklist
|
||||
capability rather than a yes/no checklist.
|
||||
|
||||
> Purpose. Fourteen tools/systems have now been studied (plus the wiki-engines
|
||||
> landscape): two conceptual ancestors (**Xanadu, ZigZag**); four engines (**XWiki,
|
||||
> TWiki, Foswiki** + landscape); and the modern note/PKB tools (**Roam, Obsidian,
|
||||
> Notion, Joplin, Logseq, Anytype, AFFiNE, AppFlowy, Trilium**), against the federation
|
||||
> and origin research. This document reads them *across* each other. The payoff is a
|
||||
> small set of **capability spectra** — now **thirteen** — each anchored at both ends by
|
||||
> a real system, with federation operations degrading by position. That spectrum *is*
|
||||
> the adapter contract's design surface. v2 folds the post-engine use cases (**UC-44–
|
||||
> UC-67**) into the `SHARD-WP-0002` tasks.
|
||||
> Purpose. ~23 tools/systems have now been studied. Two conceptual ancestors (**Xanadu,
|
||||
> ZigZag**); the file/DB engines (**XWiki, TWiki, Foswiki**, + landscape); the modern
|
||||
> note/PKB tools (**Roam, Obsidian, Notion, Joplin, Logseq, Anytype, AFFiNE, AppFlowy,
|
||||
> Trilium**); and the WP-0003 batch (**Federated Wiki, Wikibase, forge wikis, TiddlyWiki,
|
||||
> ikiwiki, Quip, MojoMojo, Oddmuse, UseModWiki**), against the federation and origin
|
||||
> research. This document reads them *across* each other. The payoff is a small set of
|
||||
> **capability spectra** — now **fourteen** per-shard, plus a **federation-model taxonomy**
|
||||
> for the coordination layer — each anchored at both ends by a real system, with federation
|
||||
> operations degrading by position. That spectrum *is* the adapter contract's design
|
||||
> surface. v3 folds the WP-0003 use cases (**UC-68–UC-82**) into the `SHARD-WP-0002` tasks.
|
||||
|
||||
Inputs: `research/260608-{federation-concepts,wikiengines-overview,c2-wiki-origins,yawex-prior-art}`,
|
||||
`research/260613-{xwiki,twiki,foswiki}-deep-dive`,
|
||||
`research/260614-{xanadu,zigzag,roam,obsidian,notion,joplin,logseq,localfirst-workspaces,trilium}-deep-dive`.
|
||||
`research/260614-{xanadu,zigzag,roam,obsidian,notion,joplin,logseq,localfirst-workspaces,trilium,wikijs,federated-wiki,wikibase,forge-wikis,tiddlywiki,ikiwiki,quip,mojomojo,oddmuse,usemodwiki}-deep-dive`.
|
||||
Output target: `spec/TechnicalSpecificationDocument.md` (adapter contract) via
|
||||
`SHARD-WP-0002`.
|
||||
|
||||
@@ -29,238 +34,373 @@ Output target: `spec/TechnicalSpecificationDocument.md` (adapter contract) via
|
||||
## 1. The shard family matrix
|
||||
|
||||
Candidate-shard backends across the dimensions that matter to the contract. (Xanadu and
|
||||
ZigZag are *not* shards — they are the conceptual ideals each column aspires to; listed
|
||||
last as reference anchors.)
|
||||
ZigZag are *not* shards — they are the conceptual ideals each column aspires to; Federated
|
||||
Wiki is *barely* a shard — it is mostly a **federation model**, see §2.5; both listed apart.)
|
||||
|
||||
| Backend | Substrate | Attach mode(s) | Addressing | Structure | History | Merge | Query | →Markdown | Opacity |
|
||||
|---------|-----------|----------------|-----------|-----------|---------|-------|-------|-----------|---------|
|
||||
| **Git folder / repo** | files | file-store | path (+ commit) | flat MD + frontmatter | **git-native** | git/text | no | native | none |
|
||||
| **Git folder / forge wiki** | files (`.wiki.git`) | **file-store (git IS store)** | path (+ commit) | flat MD + frontmatter | **git-native** | git/text | no | native | none |
|
||||
| **ikiwiki** | files (git) → static HTML | file-store (source repo) | path | flat MD + directives | **git-native** | git/text | no | native (src) | none |
|
||||
| **Obsidian** | files | file-store **/** plugin | path + in-file `^id` | frontmatter (in-file) | none (Git plugin) | git/text | plugin (Dataview) | native (OFM) | none |
|
||||
| **Logseq** | files (MD/Org) → SQLite (DB-graph) | file-store **/** plugin | **in-file block `id::`** (sweet spot) | `key::` props (in-file) | none (git) | git/text | **Datalog (derived)** | native-ish | none |
|
||||
| **TWiki / Foswiki** | files + RCS / pluggable | file-store **/** API | path | `%META%` in-file (N records) | **open file (RCS/PlainFile)** | git/text | no | lossless (TML) | none |
|
||||
| **Trilium** | SQLite (one file) | **ETAPI** / scripting / DB | `noteId` + **`branchId`** (id≠place) | labels+relations, **inherited+templated**; **DAG** | internal revisions | conflict-res | attr search | **lossy (HTML)** | **per-note** |
|
||||
| **Joplin** | SQLite-local | **sync-mirror** / local-REST / plugin | page-level `:/id` (store) | notebooks + tags | internal revisions | conflict-notes | search | lossy | E2EE (whole) |
|
||||
| **Logseq** | files (MD/Org) → SQLite | file-store **/** plugin | **in-file block `id::`** (sweet spot) | `key::` props (in-file) | none (git) | git/text | **Datalog (derived)** | native-ish | none |
|
||||
| **TiddlyWiki** | single HTML **/** `.tid` dir | **file-store (container/`.tid`)** | tiddler `title` | typed tiddler **fields** | none / git (.tid) | git/text | **filters** | varies (`type`) | none |
|
||||
| **TWiki / Foswiki** | files + RCS / pluggable | file-store **/** API | path | `%META%` in-file (N records) | **open file (RCS)** | git/text | no | lossless (TML) | none |
|
||||
| **Oddmuse / UseModWiki** | flat files (CGI) | file-store (**minimal floor**) | CamelCase/path | none (flat) | flat-file, **partial** | last-writer | no | lossy | none |
|
||||
| **MojoMojo** | relational DB | **direct-DB-read** | page row / path | relational rows+lineage | **DB version rows** | last-writer | SQL | MD-in-column | none |
|
||||
| **Trilium** | SQLite (one file) | ETAPI / scripting / DB | `noteId` + **`branchId`** (id≠place) | labels+relations, **inherited+templated**; **DAG** | internal revisions | conflict-res | attr search | **lossy (HTML)** | **per-note** |
|
||||
| **Joplin** | SQLite-local | **sync-mirror** / local-REST / plugin | page-level `:/id` | notebooks + tags | internal revisions | conflict-notes | search | lossy | E2EE (whole) |
|
||||
| **Wiki.js** | DB ↔ git mirror | file-store(mirror) / **GraphQL** | path | frontmatter (mirror) | git (via mirror) | git/text | GraphQL | native (mirror) | none |
|
||||
| **XWiki** | DB (Hibernate) | in-engine host / REST | path | **XObjects/XClass** | internal (`xwikircs`) | git/text | yes (XWQL) | engine syntax | none |
|
||||
| **Quip** | hosted (SaaS) | **external-API (HTML)** | doc id + section anchor | **prose + inline spreadsheets/live-apps** | internal | server (OT) | no | **lossy (HTML)** | proprietary |
|
||||
| **Roam** | client DataScript | **in-app host only** | **store UUID** | `key::` attrs | internal (txn log) | (in-app) | yes (Datalog) | (Roam MD) | none |
|
||||
| **Notion** | hosted Postgres | **external API only** | store UUID | **DB schema + relations + rollups** | internal, not portable | internal | yes (DB query) | **lossy** | none |
|
||||
| **Notion** | hosted Postgres | **external-API (block-JSON)** | store UUID | **DB schema + relations + rollups** | internal, not portable | internal | yes (DB query) | **lossy** | none |
|
||||
| **Wikibase / Wikidata** | MediaWiki + RDF index | external-API + **SPARQL** | **opaque Q/P id + stmt GUID** | **typed entity-statement graph** | page revisions (JSON) | last-writer + **rank** | **SPARQL (+SERVICE)** | **lossy (not MD)** | none |
|
||||
| **Anytype** | **CRDT (any-sync)** | **replica / P2P node** | object id (store) | **typed object graph (ontology)** | CRDT log | **native-CRDT** | graph | lossy | **E2EE (whole)** |
|
||||
| **AFFiNE** | **CRDT (Yjs)** | replica / self-host | block id (store) | blocks; **one-data-many-views** | CRDT log | **native-CRDT** | DB filters | lossy | optional |
|
||||
| **AppFlowy** | **CRDT (Yrs)** | replica / self-host | block id (store) | **Notion-style DB + views** | CRDT log | **native-CRDT** | DB query | lossy | self-host |
|
||||
| **TiddlyWiki** | single file | file-store | path | typed tiddlers | none | git/text | no | varies | none |
|
||||
| **MediaWiki / Confluence** | DB | API | path | wikitext / macros | internal-only | internal | limited | lossy | none |
|
||||
| — *Federated Wiki (mostly a federation model, §2.5)* | per-page JSON | **REST/file-store hybrid** | story-item `id` | typed story items | **append-only journal** | **fork + journal-replay** | neighborhood search | wiki-ish | none |
|
||||
| — *Xanadu (ideal)* | permascroll | — | **tumbler (span)** | spans + links | permanent | content-merge | — | — | — |
|
||||
| — *ZigZag (ideal)* | cells/dims | — | cell id | **N dimensions** | — | — | dimension walk | — | — |
|
||||
|
||||
Reading top to bottom is roughly shard-wiki's difficulty gradient: **Git/Obsidian/
|
||||
Logseq** are friction-free file-store cases (Logseq adding block addressing on files);
|
||||
**TWiki/Foswiki/Trilium** add translation and (Trilium) a DAG + computed metadata;
|
||||
**XWiki/Roam/Notion** add DB structure and store addressing; the **CRDT cohort
|
||||
(Anytype/AFFiNE/AppFlowy)** adds a new merge model and (Anytype) P2P+E2EE; **Notion** is
|
||||
the hardest hosted case. Xanadu/ZigZag mark the ideals.
|
||||
Reading top to bottom is roughly shard-wiki's difficulty gradient, now with both ends
|
||||
extended: the **flat-file floor (Oddmuse/UseModWiki)** anchors the bottom — minimal, partial
|
||||
history, the field's common ancestor; **git/forge wikis, ikiwiki, Obsidian, Logseq,
|
||||
TiddlyWiki** are friction-free file-store cases (forge wikis make *git the store itself*);
|
||||
**TWiki/Foswiki/Trilium/Wiki.js** add translation, DAG/computed metadata, or a git mirror;
|
||||
**MojoMojo** needs direct-DB reads; **XWiki/Roam/Notion/Quip** add DB/SaaS structure and
|
||||
store/API addressing; **Wikibase** is the **typed-knowledge-graph far-end** (SPARQL,
|
||||
statement-level provenance); the **CRDT cohort** adds native merge + (Anytype) P2P/E2EE.
|
||||
Xanadu/ZigZag mark the ideals; Federated Wiki marks the federation-model ideal (§2.5).
|
||||
|
||||
---
|
||||
|
||||
## 2. The capability spectra (the contract's real shape) — thirteen
|
||||
## 2. The capability spectra (the contract's real shape) — fourteen
|
||||
|
||||
Each capability is **not boolean** — it is a position on a spectrum anchored at each end
|
||||
by a real system. The contract should model *positions*; federation ops degrade by
|
||||
position.
|
||||
Each capability is **not boolean** — it is a position on a spectrum anchored at each end by
|
||||
a real system. The contract models *positions*; federation ops degrade by position.
|
||||
|
||||
1. **Addressing granularity** — `none → whole-page(path) → page-level store id(Joplin
|
||||
:/id, Trilium noteId) → in-file span(Obsidian ^id) → in-file block(Logseq id::, the
|
||||
sweet spot: block-level AND git-diffable) → store-minted span(Roam/Notion/CRDT UUID) →
|
||||
portable tumbler(Xanadu ideal)`. (UC-51, UC-44/45.)
|
||||
2. **Content identity** — `none → path/title → fingerprint(hash) → span-set/equivalence
|
||||
(Xanadu)`. Drives equivalence + reverse-transclusion. (UC-46, UC-27.)
|
||||
3. **Identity vs placement** *(new emphasis)* — `path = identity(most) → identity
|
||||
separated from placement(Trilium note/branch; a page in many locations = a DAG)`. The
|
||||
clean model for a page under multiple paths/shards. (UC-66, UC-22.)
|
||||
4. **Structure** — `flat Markdown → in-file frontmatter/key::(Obsidian/Logseq) → in-file
|
||||
%META%(TWiki) → typed objects(XWiki) → DB schema+relations+rollups(Notion/AppFlowy) →
|
||||
typed object graph/ontology(Anytype) → computed: inherited+templated(Trilium)`.
|
||||
In-text federates; DB-locked needs sidecar+fidelity; **computed** needs effective-vs-
|
||||
own provenance. (UC-34, UC-39, UC-58, UC-67.)
|
||||
5. **History** — `none → internal-only/not-portable(Notion/Joplin/Trilium) → CRDT update
|
||||
log(Anytype/AFFiNE/AppFlowy) → open file format(TWiki RCS) → git-native(Git/Obsidian/
|
||||
Logseq)`. Internal/CRDT-log ⇒ *supplement*; open-file ⇒ *import*; git ⇒ *adopt*.
|
||||
(UC-36, UC-41.)
|
||||
6. **Merge model** *(new, 13th)* — `none → git/text merge → conflict-notes/keep-both
|
||||
(Joplin) → native-CRDT conflict-free(Anytype/AFFiNE/AppFlowy)`. A CRDT shard merges
|
||||
itself — **never impose git/text merge**; speak the CRDT (replica) or stay projection/
|
||||
overlay. (UC-64.)
|
||||
7. **Native query** — `none → text search → build-your-own derived index(Logseq DataScript
|
||||
over files; shard-wiki can do likewise) → datalog/graph(Roam/Anytype) → DB query
|
||||
(Notion/AppFlowy/XWiki)`. Delegate where present; **build an index over the projection**
|
||||
where not. (UC-52, UC-63, UC-05, UC-54.)
|
||||
1. **Addressing granularity** — `none → whole-page(path) → page-level store id(Joplin :/id,
|
||||
Trilium noteId) → in-file span(Obsidian ^id) → in-file block(Logseq id::, the sweet spot:
|
||||
block-level AND git-diffable) → store-minted span(Roam/Notion/CRDT UUID) → statement GUID
|
||||
(Wikibase) → portable tumbler(Xanadu ideal)`. Story-item `id` (Federated Wiki) is a
|
||||
mid-tier within-page handle. (UC-51, UC-44/45, UC-73.)
|
||||
2. **Content identity** — `none → path/title → opaque stable id, labels-as-annotation
|
||||
(Wikibase Q/P) → fingerprint(hash) → span-set/equivalence(Xanadu)`. Wikibase is the
|
||||
cleanest real instance of **stable, language-neutral identity**. (UC-46, UC-27, UC-73.)
|
||||
3. **Identity vs placement** — `path = identity(most) → identity separated from placement
|
||||
(Trilium note/branch; a page in many locations = a DAG) → provenance-edge links across
|
||||
sites (Federated Wiki fork-DAG; forge wiki = path, identity layered above)`. The clean
|
||||
model for a page under multiple paths/shards. (UC-66, UC-22, UC-71.)
|
||||
4. **Structure** — `flat Markdown(Oddmuse) → in-file frontmatter/key::(Obsidian/Logseq) →
|
||||
in-file %META%(TWiki) → tiddler fields(TiddlyWiki) → relational rows(MojoMojo) → typed
|
||||
objects(XWiki) → DB schema+relations+rollups(Notion/AppFlowy) → prose+inline-embedded
|
||||
objects(Quip) → typed object graph/ontology(Anytype) → computed inherited+templated
|
||||
(Trilium) → typed entity-statement knowledge graph(Wikibase)`. In-text federates;
|
||||
DB-locked needs sidecar+fidelity; **graph/computed** needs effective-vs-own +
|
||||
render-without-flatten. (UC-34, UC-39, UC-58, UC-67, UC-73, UC-80.)
|
||||
5. **History** — `none → partial/truncated flat-file(Oddmuse keep/) → internal-only/
|
||||
not-portable(Notion/Joplin/Trilium) → DB version rows(MojoMojo) → CRDT update log
|
||||
(Anytype/AFFiNE/AppFlowy) → append-only semantic journal(Federated Wiki) → open file
|
||||
format(TWiki RCS) → git-native(Git/forge/ikiwiki/Obsidian/Logseq/Wiki.js mirror)`.
|
||||
Internal/CRDT/DB-rows ⇒ *supplement*; open-file/journal ⇒ *import*; git ⇒ *adopt*.
|
||||
**Completeness is metadata** (Oddmuse history is partial — never imply complete). (UC-36,
|
||||
UC-41, UC-71, UC-81, UC-82.)
|
||||
6. **Merge model** — `none → last-writer → git/text 3-way merge → conflict-notes/keep-both
|
||||
(Joplin) → fork + manual journal-replay(Federated Wiki) → coexist-with-rank(Wikibase:
|
||||
contradictory values kept, curated) → native-CRDT conflict-free(Anytype/AFFiNE/AppFlowy)`.
|
||||
Four+ distinct models — never impose git/text merge on a CRDT or a journal shard; speak
|
||||
the shard's model or stay projection/overlay. (UC-64, UC-71, UC-75.)
|
||||
7. **Native query** — `none → text search → filter expressions(TiddlyWiki) → build-your-own
|
||||
derived index(Logseq DataScript over files; shard-wiki can do likewise) → datalog/graph
|
||||
(Roam/Anytype) → DB query(Notion/AppFlowy/XWiki) → SPARQL/RDF + federated SERVICE
|
||||
(Wikibase, the far-end + query-time cross-shard join)`. Delegate where present; **build an
|
||||
index over the projection** where not. (UC-52, UC-63, UC-05, UC-54, UC-74.)
|
||||
8. **Translation to Markdown** — `native → lossless round-trip(Foswiki TML↔HTML) → lossy-
|
||||
with-fidelity-report(HTML/CKEditor Trilium; Notion blocks; CRDT/object models)`.
|
||||
Lossless ⇒ writable; lossy ⇒ read/projection floor + visible fidelity loss. (UC-42,
|
||||
UC-59, UC-03.)
|
||||
9. **Attachment mode** *(expanded)* — a **per-binding, capability-gated** choice; a
|
||||
backend may offer several:
|
||||
- **file-store** — *native on-disk store*(Obsidian/Logseq/TWiki) **or** *interchange/
|
||||
sync mirror*(Joplin items on WebDAV/S3) (UC-40, UC-53, UC-60, UC-62)
|
||||
- **in-engine host** — adapter inside the app via its API (Roam/Obsidian/Logseq/
|
||||
Trilium scripting, XWiki components) (UC-38, UC-50)
|
||||
with-fidelity-report(HTML/CKEditor Trilium; Notion blocks; Quip HTML+embedded objects;
|
||||
CRDT/object models) → not-Markdown-at-all(Wikibase statements → lossy render or keep
|
||||
graph)`. Lossless ⇒ writable; lossy ⇒ read/projection floor + visible fidelity loss;
|
||||
not-MD ⇒ structured payload + optional rendered view. (UC-42, UC-59, UC-03, UC-73, UC-80.)
|
||||
9. **Attachment mode** — a **per-binding, capability-gated** choice; a backend may offer
|
||||
several. The full taxonomy:
|
||||
- **file-store** — *native on-disk store* (Obsidian/Logseq/TWiki), *git IS the store*
|
||||
(forge `.wiki.git`, ikiwiki source), *single-file container* (TiddlyWiki HTML),
|
||||
*flat-file floor* (Oddmuse), **or** *interchange/sync mirror* (Joplin; Wiki.js git
|
||||
mirror) (UC-40, UC-53, UC-60, UC-62, UC-76, UC-78, UC-79, UC-82, UC-68)
|
||||
- **in-engine host** — adapter inside the app via its API (Roam/Obsidian/Logseq/Trilium
|
||||
scripting, XWiki components) (UC-38, UC-50)
|
||||
- **local-REST** — localhost API, app-running (Joplin Data API; Trilium ETAPI) (UC-38)
|
||||
- **external-API** — remote REST from outside (Notion) (UC-57)
|
||||
- **external-API** — remote API from outside, with a **payload-format facet**:
|
||||
*block-JSON* (Notion, UC-57), *GraphQL* (Wiki.js, UC-69), *HTML* (Quip, UC-80),
|
||||
*forge wiki REST* (GitLab/Gitea, UC-77), *MediaWiki/SPARQL* (Wikibase, UC-73/74)
|
||||
- **direct-DB-read** — read the engine's relational store (MojoMojo) when no file/API
|
||||
exists; schema = a versioned coupling (UC-81)
|
||||
- **CRDT replica** — hold a local CRDT replica (Anytype/AFFiNE/AppFlowy) (UC-64)
|
||||
- **P2P / no-central-endpoint** — replica or peer/node, not a URL (Anytype) (UC-65)
|
||||
- **REST/file-store hybrid** — page JSON over HTTP+CORS or static files (Federated Wiki)
|
||||
(UC-70)
|
||||
10. **Operational envelope** — `local/unbounded → realtime CRDT/WebSocket → rate-limited+
|
||||
eventually-consistent+paginated(Notion ~3 rps)`. Sets live vs cache/poll/webhook.
|
||||
(UC-57, UC-31.)
|
||||
11. **Access grant** — `open(L0) → token → OAuth scoped+revocable(Notion) → P2P key/invite
|
||||
(Anytype)`. The backend may *enforce* no-silent-mutation. (UC-57, UC-65,
|
||||
[[shard-wiki-auth-in-core-decision]].)
|
||||
12. **Content opacity** *(new, 12th)* — `plaintext → encrypted-at-rest whole-shard(Joplin/
|
||||
Anytype E2EE) → per-item(Trilium protected notes — encrypted and plaintext coexist)`.
|
||||
Opaque content ⇒ backup/structure-shell only; never present ciphertext as readable.
|
||||
(UC-61.)
|
||||
13. **Write granularity** — `whole-file(TiddlyWiki) → per-page/note(Git/Obsidian/Joplin/
|
||||
Trilium) → per-block(Roam/Notion/Logseq/CRDT)`. Sets overlay/patch/lock/conflict
|
||||
scope. (UC-35.)
|
||||
eventually-consistent+paginated(Notion ~3 rps, Quip, Wikibase public endpoints)`. Sets
|
||||
live vs cache/poll/webhook. (UC-57, UC-31.)
|
||||
11. **Access grant** — `open(L0; Oddmuse) → token → OAuth scoped+revocable(Notion) →
|
||||
enterprise SSO + ACL(Quip/Salesforce, Wiki.js path rules) → P2P key/invite(Anytype) →
|
||||
own-site-only writes(Federated Wiki)`. The backend may *enforce* no-silent-mutation.
|
||||
(UC-57, UC-06, UC-65, [[shard-wiki-auth-in-core-decision]].)
|
||||
12. **Content opacity** — `plaintext(files) → proprietary-but-lossy-exportable(Quip HTML;
|
||||
Notion) → encrypted-at-rest whole-shard(Joplin/Anytype E2EE) → per-item(Trilium
|
||||
protected notes)`. Opaque ⇒ backup/structure-shell; never present ciphertext (or imply
|
||||
a lossy export is faithful) as readable. (UC-61, UC-80.)
|
||||
13. **Write granularity** — `whole-file(TiddlyWiki single-file) → per-page/note(Git/forge/
|
||||
Obsidian/Joplin/Trilium/Oddmuse) → story-item/paragraph(Federated Wiki) → section-anchor
|
||||
splice(Quip) → per-statement(Wikibase API) → per-block(Roam/Notion/Logseq/CRDT)`. Sets
|
||||
overlay/patch/lock/conflict scope; whole-file ⇒ **no per-page atomicity**. (UC-35,
|
||||
UC-78.)
|
||||
14. **Provenance granularity** *(new, 14th)* — `none → per-shard → per-page(most; author/
|
||||
time) → per-commit(git) → per-edit(journal entry, Federated Wiki) → per-statement/value
|
||||
(Wikibase references + rank)`. How finely the union can attribute and source content;
|
||||
Wikibase pushes provenance below the page (sourced, contradictory values coexist with a
|
||||
curation signal). The page model + journal should *allow* sub-page provenance even if MVP
|
||||
records per page. (UC-24, UC-71, UC-75.)
|
||||
|
||||
*(Content types — Markdown-only → typed records → non-Markdown assets (Excalidraw/Canvas/
|
||||
whiteboards/objects) — remains a cross-cutting page-model demand, tracked under structure
|
||||
+ T12 rather than as a standalone capability. UC-55.)*
|
||||
*(Content types — Markdown-only → typed records → inline-embedded objects (Quip
|
||||
spreadsheets) → non-Markdown assets (Excalidraw/Canvas/whiteboards) → typed-graph statements
|
||||
(Wikibase) — remains a cross-cutting page-model demand, tracked under structure + T12 rather
|
||||
than as a standalone capability. UC-55.)*
|
||||
|
||||
Design consequence: **T11's capability vocabulary = these thirteen spectra**, not a flat
|
||||
Design consequence: **T11's capability vocabulary = these fourteen spectra**, not a flat
|
||||
`read/write/diff/...` list. The flat verbs remain the *operations*; the spectra are the
|
||||
*profile* saying how well each verb is supported and how it degrades.
|
||||
*profile* saying how well each verb is supported and how it degrades. The **floor**
|
||||
(Oddmuse/UseModWiki) and **far-ends** (Wikibase graph/query/provenance; CRDT merge; Notion
|
||||
hosted) bound every spectrum with a real system.
|
||||
|
||||
---
|
||||
|
||||
## 2.5. The federation-model taxonomy (the coordination-layer axis) — new in v3
|
||||
|
||||
The fourteen spectra above describe a *single shard's* capabilities. The WP-0003 batch
|
||||
revealed a second, orthogonal axis the v2 synthesis under-modelled: **federation itself is
|
||||
plural.** "Attach many shards and present a union" can be realized by several distinct
|
||||
coordination models, each a real system, each with different reconciliation semantics. This
|
||||
axis lives at shard-wiki's **coordination layer** (`SHARD-WP-0002` T1–T6), not in a single
|
||||
adapter.
|
||||
|
||||
| Federation model | Exemplar | Mechanism | Reconciliation | Discovery |
|
||||
|------------------|----------|-----------|----------------|-----------|
|
||||
| **Fork + journal** | Federated Wiki | copy page to own site; append-only semantic **journal** records `fork`-with-source | **manual**: compare journals, fork the version you prefer; **chorus**, no canonical | link + fork (**neighborhood**) / curated **roster** |
|
||||
| **VCS replication + ping** | ikiwiki | git clone/pull/push between instances; **XML-RPC pinger** notifies peers to pull/rebuild | **git merge** across clones | configured peers + pings |
|
||||
| **Query-time graph join** | Wikibase | **SPARQL `SERVICE`** runs a sub-query on another endpoint and joins | none (read-time join; rank curates conflicts) | endpoint URLs |
|
||||
| **Feed aggregation** | ikiwiki `aggregate`, RSS/Atom | pull remote feeds in as pages | one-way inbound projection | feed URLs |
|
||||
| **Activity streams** | ActivityPub (federation research) | actor/inbox/outbox Create/Update | per-actor; eventual | actor handles |
|
||||
| **Engine-maintained mirror** | Wiki.js git mirror | DB-canonical engine syncs to a git mirror | engine owns DB↔git sync (don't double-sync) | the mirror repo |
|
||||
|
||||
Two cross-cutting lessons:
|
||||
|
||||
- **git-IS-store vs engine-mirror resolves the write-race.** A **forge wiki** (`.wiki.git`)
|
||||
and **ikiwiki source** make *git the canonical store*, so **write-by-commit is safe** — no
|
||||
engine to race. Wiki.js (engine-mirror, DB canonical) is the opposite and needs care. The
|
||||
contract must record *which side is source of truth* per binding. (Resolves UC-68's open
|
||||
race for the git-canonical case; UC-76.)
|
||||
- **shard-wiki's own coordination journal should be journal-shaped.** Federated Wiki proves
|
||||
the **append-only semantic-op log with provenance entries, page-state-as-derived-replay**
|
||||
pattern in production — the concrete shape for INTENT's coordination journal (UC-71), and a
|
||||
superset that can *ingest* git history, CRDT logs, DB version rows, and partial flat-file
|
||||
histories as differently-grained inputs.
|
||||
|
||||
Design consequence: **T1–T6 should model federation as a selectable model (or composition of
|
||||
models), not a single hard-coded flow** — mechanism over policy at the coordination layer,
|
||||
mirroring how T11 models per-shard capability as spectra. A given information space may use
|
||||
fork+journal for human-curated shards, VCS-replication for git shards, query-join for graph
|
||||
shards, and feed-aggregation for read-only sources — concurrently.
|
||||
|
||||
---
|
||||
|
||||
## 3. Cross-cutting findings (the through-lines)
|
||||
|
||||
- **Files-canonical, index-derived is the winning architecture.** Obsidian's
|
||||
MetadataCache, **Logseq's DataScript-over-files**, Git's working tree, and shard-wiki's
|
||||
projection model agree: the graph/backlinks/structured index are **derived and
|
||||
rebuildable**, never a second source of truth. Roam/Notion/CRDT invert this (store
|
||||
canonical) and pay in portability. shard-wiki keeps files+journal canonical.
|
||||
- **Fine-grained addressing is real, adoptable, and can be git-diffable.** Roam/Notion/
|
||||
CRDT mint store UUIDs; Obsidian uses in-file `^id`; **Logseq resolves the tension —
|
||||
block-level `id::` that is also git-diffable text**. Adopt native IDs where present,
|
||||
fingerprint where not; portable span address stays the open ideal (Xanadu).
|
||||
- **Identity ≠ placement.** *(new)* Trilium's **note vs branch** (a note cloned into many
|
||||
locations = a DAG) is the clean model for a page under multiple paths or across shards —
|
||||
separate *what a page is* from *where it sits*. The namespace-level form of the clone/
|
||||
reference primitive.
|
||||
- **Transclusion ⇄ clone ⇄ embed ⇄ cloned-note is one primitive.** Xanadu transclusion,
|
||||
ZigZag clone, Roam/Logseq embed, Obsidian `![[ ]]`, Notion synced block, **Trilium note
|
||||
cloning** — one "reference-not-copy" primitive over an addressable union (UC-32/44/45/
|
||||
51/66).
|
||||
- **CRDT changes the merge math.** *(new)* The CRDT cohort merges concurrent edits itself;
|
||||
shard-wiki must **not impose git/text merge** — speak the CRDT (replica) or stay a
|
||||
projection/overlay. A new **merge-model** capability (spectrum 6).
|
||||
- **Structure & history federate iff in text; metadata can be computed.** `%META%`/
|
||||
frontmatter/`key::` diff and travel; XObjects/Notion-DB/CRDT lock in. *(new)* Trilium
|
||||
adds **computed metadata** (inherited+templated) — represent effective-vs-own, don't
|
||||
flatten.
|
||||
- **Content opacity is per-item, not only whole-shard.** *(new)* Joplin/Anytype encrypt
|
||||
whole-shard; **Trilium encrypts per-note** — the opacity capability must be granular.
|
||||
- **The attach surface is not always the native store.** *(new)* Joplin's best surface is
|
||||
its **sync mirror** (not its SQLite); Logseq offers file-graph **or** DB-graph, and is
|
||||
**migrating substrate** (file→SQLite). Bind to capabilities, not to "it's files."
|
||||
- **The page model must stretch many ways at once:** prose Markdown, typed/computed
|
||||
records (N-per-page, relations, inheritance), non-Markdown assets, reference/query-
|
||||
defined pages, and **multi-placement (DAG) identity**. The heaviest demand on T12.
|
||||
- **Files-canonical, index-derived is the winning architecture.** Obsidian's MetadataCache,
|
||||
**Logseq's DataScript-over-files**, Git's working tree, **Wikibase's WDQS (SPARQL index
|
||||
rebuilt from canonical JSON entities)**, and shard-wiki's projection model agree: the
|
||||
graph/backlinks/query index is **derived and rebuildable**, never a second source of truth.
|
||||
Roam/Notion/CRDT invert this (store canonical) and pay in portability. shard-wiki keeps
|
||||
files + journal canonical.
|
||||
- **Git is both the home store and the home journal.** *(sharpened in v3)* Forge wikis make
|
||||
git *the* store; ikiwiki and Wiki.js make git the source or mirror; for all of them the
|
||||
**git log is the coordination journal with zero synthesis**. The git-canonical cases are
|
||||
the friction-free core; everything else is measured as deviation.
|
||||
- **The flat-file floor is the field's common root.** *(new)* Oddmuse and UseModWiki
|
||||
(Wikipedia's MediaWiki Phase I) show the minimal plain-text page+history wiki is the
|
||||
ancestor every richer engine elaborates — so the **minimal/floor capability profile** is
|
||||
the right baseline, and shard-wiki's page model must stay attach-compatible with it
|
||||
(flat files, CamelCase identities, **partial** history). (UC-82.)
|
||||
- **Federation is plural** *(new — §2.5).* Fork+journal, VCS-replication+ping, query-time
|
||||
graph join, feed aggregation, activity streams, engine-mirror — distinct coordination
|
||||
models, selectable and composable, not one flow.
|
||||
- **Provenance has a granularity spectrum** *(new — spectrum 14).* From per-shard down to
|
||||
**per-statement/value** (Wikibase references + rank). Union-without-erasure includes
|
||||
*attribution at the right grain* and letting sourced contradictions coexist with curation.
|
||||
- **Identity ≠ placement.** Trilium's **note vs branch** (a note cloned into many locations =
|
||||
a DAG) and Wikibase's **opaque stable IDs (labels-as-annotation)** are the clean models:
|
||||
separate *what a page is* from *where it sits* and from *what it's called*. Federated
|
||||
Wiki's fork entries are **provenance edges** between same-named pages across sites.
|
||||
- **Transclusion ⇄ clone ⇄ embed ⇄ cloned-note ⇄ reference is one primitive** over an
|
||||
addressable union (Xanadu, ZigZag, Roam/Logseq, Obsidian `![[ ]]`, Notion synced block,
|
||||
Trilium cloning, TiddlyWiki `{{ }}`). (UC-32/44/45/51/66.)
|
||||
- **CRDT changes the merge math; journals and rank add more models.** *(extended)* The merge
|
||||
spectrum now spans last-writer → git 3-way → conflict-notes → **fork+journal-replay** →
|
||||
**coexist-with-rank** → native-CRDT. Never impose git/text merge across that range.
|
||||
- **Structure & history federate iff in text; metadata can be computed; the far-end is a
|
||||
graph.** `%META%`/frontmatter/`key::`/tiddler-fields diff and travel; XObjects/Notion-DB/
|
||||
CRDT/Quip-objects lock in; Trilium computes metadata (inherited+templated); **Wikibase is
|
||||
a full typed knowledge graph** — render to Markdown is lossy, so keep the graph and offer a
|
||||
view, never silent-flatten.
|
||||
- **The attach surface is rarely "just files," and source-of-truth varies.** *(extended)*
|
||||
Joplin's best surface is its sync mirror; Logseq offers file-graph or DB-graph and is
|
||||
migrating substrate; **forge wikis = git-canonical (write freely)** vs **Wiki.js =
|
||||
DB-canonical mirror (write carefully)** vs **MojoMojo = DB-only (direct read)**. Bind to
|
||||
capabilities *and* record the source of truth.
|
||||
- **The page model must stretch many ways at once:** prose Markdown, typed/computed records
|
||||
(N-per-page, relations, inheritance), **inline-embedded objects** (Quip), **typed-graph
|
||||
statements** (Wikibase), non-Markdown assets, reference/query-defined pages, and
|
||||
**multi-placement (DAG) identity**. The heaviest demand on T12.
|
||||
|
||||
---
|
||||
|
||||
## 4. How the post-engine use cases fold into the workplan
|
||||
## 4. How the use cases fold into the workplan
|
||||
|
||||
UC-44–UC-67 (from the 260614 dives) map onto the adapter-contract tasks:
|
||||
The 260614 + WP-0003 use cases (UC-44–UC-82) map onto the adapter-contract and federation
|
||||
tasks:
|
||||
|
||||
| UCs | Theme | Lands in |
|
||||
|-----|-------|----------|
|
||||
| UC-35, UC-50, UC-53, UC-57, **UC-60, UC-62, UC-64, UC-65** | attachment modes (file-store native/mirror, in-engine, local-REST, external-API, CRDT-replica, P2P) + operational envelope + merge model | **T11** + **T14** |
|
||||
| UC-34, UC-39, UC-55, UC-58, **UC-67** | structured/typed/**computed** payload, non-MD assets, DB schema+relations | **T12** |
|
||||
| UC-36 | internal/CRDT-log history = supplement | **T13** |
|
||||
| UC-42, UC-59 | translation: lossless vs lossy-with-fidelity-report (HTML/blocks/CRDT) | **T15** |
|
||||
| UC-31 | webhooks / realtime / push-vs-poll | **T6** / **T11** envelope |
|
||||
| UC-57 §6, **UC-61, UC-65** | scoped grant; **content opacity** (whole/ per-item); P2P key | **T11** (access-grant + opacity) |
|
||||
| UC-44, UC-45, UC-46, UC-51, **UC-63, UC-66** | span addressing, content identity, **identity≠placement**, transclusion-as-reference, derived index | **T16** (+ T12) |
|
||||
| UC-47, UC-48, UC-52, UC-54 | dimensional navigation, query delegation/build, query-defined pages | **T16** (+ T5/T10) |
|
||||
| UC-35, UC-50, UC-53, UC-57, UC-60, UC-62, UC-64, UC-65, **UC-68, UC-70, UC-76, UC-77, UC-78, UC-79, UC-80, UC-81, UC-82** | attachment modes (file-store native/git-IS-store/container/mirror, in-engine, local-REST, external-API w/ payload-format, direct-DB, CRDT-replica, P2P, REST/file-store-hybrid) + operational envelope | **T11** + **T14** |
|
||||
| UC-34, UC-39, UC-55, UC-58, UC-67, **UC-73, UC-80** | structured/typed/computed/**graph** payload, **inline-embedded objects**, non-MD assets | **T12** |
|
||||
| UC-36, UC-41, **UC-81, UC-82** | history: internal/CRDT-log/**DB-rows**/**partial-flat-file** = supplement; **completeness metadata** | **T13** |
|
||||
| UC-42, UC-59, **UC-73, UC-80** | translation: lossless vs lossy-with-fidelity vs **not-Markdown** (graph/HTML/objects) | **T15** |
|
||||
| UC-31, **UC-79** | webhooks / realtime / push-vs-poll / **VCS ping** | **T6** / **T11** envelope |
|
||||
| UC-57 §6, UC-61, UC-65, **UC-06, UC-80** | scoped grant; **enterprise ACL/SSO**; content opacity (whole/per-item/**lossy-exportable**); P2P key | **T11** (access-grant + opacity) |
|
||||
| UC-44, UC-45, UC-46, UC-51, UC-63, UC-66, **UC-73, UC-74** | span/statement addressing, **opaque stable identity**, identity≠placement, transclusion-as-reference, derived index, **graph query** | **T16** (+ T12) |
|
||||
| UC-47, UC-48, UC-52, UC-54, **UC-74** | dimensional navigation, query delegation/build, query-defined pages, **SPARQL/federated SERVICE** | **T16** (+ T5/T10) |
|
||||
| UC-24, **UC-71, UC-75** | **provenance granularity** (per-edit / per-statement); coordination journal shape | **T13/T16** + journal |
|
||||
| UC-26, UC-27, UC-28, UC-30, UC-05, **UC-71, UC-72, UC-79** | **federation-model taxonomy** (fork+journal, VCS-replication+ping, query-join, chorus/neighborhood/roster) | **T1–T6** |
|
||||
|
||||
No new task needed — **T16** already owns the addressing/identity/navigation thread; v2
|
||||
adds **identity≠placement (UC-66)** and **build-your-own derived index (UC-63)** to it,
|
||||
and **computed metadata (UC-67)** + **non-MD/multi-placement** to **T12**.
|
||||
The one **structural** v3 change: the **federation-model taxonomy (§2.5)** is a new design
|
||||
surface for **T1–T6** — federation becomes a *selectable, composable model* rather than a
|
||||
single flow. Per-shard, **T11** grows to **fourteen spectra** (adds provenance granularity)
|
||||
and **T14** absorbs the expanded attachment-mode taxonomy (git-IS-store, container,
|
||||
direct-DB, REST/file-store-hybrid, external-API payload-format facet).
|
||||
|
||||
---
|
||||
|
||||
## 5. Recommendations (decisions to record under SHARD-WP-0002)
|
||||
|
||||
1. **Model capabilities as the thirteen spectra (§2)**, not flat verbs. (T11.)
|
||||
2. **Two new spectra: content opacity (per-item) and merge model.** A CRDT shard's merge
|
||||
is native — never git-merge it; an encrypted shard degrades to structure-shell. (T11.)
|
||||
3. **Adopt native span IDs (prefer in-file/git-diffable, à la Logseq `id::`); fingerprint
|
||||
otherwise; keep portable-span-address open.** (T16/T11, UC-51/46.)
|
||||
4. **Separate page identity from placement** (Trilium note/branch) in the page/namespace
|
||||
model — a page is one entity with N placements (paths/shards). (T12/T16, UC-66.)
|
||||
5. **One reference-not-copy primitive** for transclusion/clone/embed/cloned-note over the
|
||||
addressable union. (T16, UC-32/44/45/66.)
|
||||
6. **Prefer in-text structure; tolerate DB structure via sidecar+fidelity; represent
|
||||
computed (inherited/templated) metadata as effective-vs-own.** (T12/T15, UC-34/58/67.)
|
||||
7. **Attachment mode is a per-binding, capability-gated choice** across the full set:
|
||||
file-store (native *or* interchange-mirror), in-engine-host, local-REST, external-API,
|
||||
CRDT-replica, P2P/no-central-endpoint. Bind to capabilities — substrate can migrate
|
||||
(Logseq). (T14, UC-40/38/50/57/60/62/64/65 + UC-43.)
|
||||
8. **Query: delegate to a native engine where present; build a derived index over the
|
||||
projection where not** (Logseq pattern). (T16/T5, UC-52/63/54.)
|
||||
9. **Keep files + coordination journal canonical; all indexes/projections derived and
|
||||
rebuildable.** (Architecture invariant, INTENT.)
|
||||
1. **Model per-shard capabilities as the fourteen spectra (§2)**, not flat verbs. (T11.)
|
||||
2. **Model federation as a selectable/composable taxonomy of models (§2.5)** — fork+journal,
|
||||
VCS-replication+ping, query-time graph join, feed aggregation, activity streams,
|
||||
engine-mirror — at the coordination layer. (T1–T6.)
|
||||
3. **Make the coordination journal journal-shaped** (Federated Wiki): append-only semantic
|
||||
ops + provenance entries, page state = derived replay; able to *ingest* git history, CRDT
|
||||
logs, DB version rows, and partial flat-file histories as differently-grained inputs.
|
||||
(T13 + journal, UC-71.)
|
||||
4. **Add provenance granularity as a spectrum** (per-shard → per-page → per-edit →
|
||||
per-statement/value); allow sub-page provenance and **coexist-with-rank** for sourced
|
||||
contradictions. (T11/T13, UC-24/75.)
|
||||
5. **Record source-of-truth per binding** and resolve the write-race accordingly:
|
||||
git-canonical (forge wiki / ikiwiki) ⇒ write-by-commit; engine-mirror (Wiki.js) ⇒ careful;
|
||||
direct-DB (MojoMojo) ⇒ read/projection/overlay default. (T14, UC-68/76/79/81.)
|
||||
6. **Expand attachment mode (§2 #9 / T14):** file-store (native / **git-IS-store** /
|
||||
**container** / mirror / **flat-file floor**), in-engine, local-REST, **external-API with
|
||||
a payload-format facet** (block-JSON/GraphQL/HTML/forge-REST/SPARQL), **direct-DB-read**,
|
||||
CRDT-replica, P2P, **REST/file-store-hybrid**. Bind to capabilities; substrate can
|
||||
migrate. (T14, UC-40/68/70/76/77/78/79/80/81/82 + UC-43.)
|
||||
7. **Page model: support a typed-graph payload and inline-embedded objects, not only
|
||||
typed records** — render to Markdown lossily, keep the graph/objects canonical; preserve
|
||||
computed (inherited/templated) metadata as effective-vs-own. (T12/T15, UC-73/80/67.)
|
||||
8. **Capability profile must express absence and partiality cleanly** (Oddmuse floor):
|
||||
sparse profiles, **partial/truncated history reported honestly**, graceful degradation to
|
||||
read/projection/overlay/backup. (T11/T13, UC-82.)
|
||||
9. **Query: SPARQL/RDF + federated `SERVICE` is the graph far-end** — delegate to native
|
||||
engines (filters/datalog/DB-query/SPARQL) where present; build a derived index over the
|
||||
projection where not. (T16/T5, UC-52/63/74.)
|
||||
10. **Adopt opaque stable identity with labels-as-annotation** (Wikibase) and **separate
|
||||
identity from placement** (Trilium note/branch); fork entries are provenance edges.
|
||||
(T16, UC-73/66/71.)
|
||||
11. **Keep files + coordination journal canonical; all indexes/projections derived and
|
||||
rebuildable.** (Architecture invariant, INTENT.)
|
||||
|
||||
These honor INTENT: mechanism over policy (spectra not hard-coded behaviors), union
|
||||
without erasure (fidelity + effective-vs-own + identity/placement all preserve
|
||||
information), graceful degradation (every capability has a read/projection floor; opaque/
|
||||
CRDT shards degrade to backup/projection), no silent mutation (access-grant + opacity +
|
||||
overlay + respect native merge), shard sovereignty (no backend forced to change
|
||||
substrate; substrate may migrate), Markdown-first/backend-neutral (in-text preferred, DB/
|
||||
CRDT/HTML tolerated).
|
||||
These honor INTENT: mechanism over policy (capability *and now federation* modelled as
|
||||
spectra/taxonomy, not hard-coded behaviors), union without erasure (fidelity +
|
||||
effective-vs-own + identity/placement + **provenance granularity** all preserve
|
||||
information), graceful degradation (every spectrum has a read/projection floor; the
|
||||
Oddmuse floor is explicit; opaque/CRDT/graph shards degrade to backup/projection/lossy-view),
|
||||
no silent mutation (access-grant + opacity + overlay + respect native merge + **source-of-
|
||||
truth per binding**), shard sovereignty (no backend forced to change substrate),
|
||||
Markdown-first/backend-neutral (in-text preferred; DB/CRDT/HTML/**graph** tolerated with a
|
||||
view).
|
||||
|
||||
---
|
||||
|
||||
## 6. Open questions escalated by the synthesis
|
||||
|
||||
1. **Portable span address** across heterogeneous backends — wrap native IDs (Roam/Notion/
|
||||
CRDT UUID, Logseq `id::`, Trilium noteId) in a shard-scoped address? (T16.)
|
||||
2. **CRDT shards** — embed a CRDT client (Yjs/Yrs) for a live replica, or consume
|
||||
snapshots? Overlays as CRDT ops or out-of-band patches? (T14, UC-64.)
|
||||
3. **Identity vs placement** — does shard-wiki adopt the note/branch split as its own page
|
||||
model, and is a cloned page one page with N placements or a transclusion? (T12/T16,
|
||||
UC-66.)
|
||||
4. **Computed metadata** — materialize effective attributes (snapshot) or compute live
|
||||
from the shard's tree/templates, with per-attribute provenance? (T12, UC-67.)
|
||||
5. **Page model breadth** — can one model carry prose + typed/computed records + non-MD
|
||||
assets + query-defined pages + multi-placement identity coherently? (T12.)
|
||||
6. **External-API write-through at scale** (Notion ~3 rps) vs read/projection default.
|
||||
(T14, UC-57.)
|
||||
7. **Content opacity** — what is visible for an opaque shard/item (IDs/structure vs
|
||||
nothing); does shard-wiki ever hold keys? (T11, UC-61.)
|
||||
1. **Federation composition** — can one information space run several federation models
|
||||
(§2.5) concurrently over different shards, and how does the union reconcile a chorus
|
||||
(fork+journal) with a canonical-asserting shard (Notion / upstream main)? (T1–T6,
|
||||
UC-72.)
|
||||
2. **Coordination-journal op vocabulary** — adopt Federated Wiki's exact ops
|
||||
(create/add/edit/move/remove/fork) at item grain, or an abstract op set other shards can
|
||||
emit, with git/CRDT/DB-row/flat-file histories ingested as inputs? (T13, UC-71.)
|
||||
3. **Provenance granularity in the model** — does the journal/page model carry per-statement
|
||||
provenance + rank (Wikibase), per-edit (journal), or per-page (MVP), configurable? (T13,
|
||||
UC-75.)
|
||||
4. **Typed-graph page** — model a Wikibase entity natively (statements) or always project to
|
||||
a lossy Markdown/table view, or both (canonical graph + view)? Is SPARQL a union-level
|
||||
capability or pass-through? (T12/T16, UC-73/74.)
|
||||
5. **Source-of-truth + write-race** — formalize git-canonical vs engine-mirror vs direct-DB
|
||||
per binding; sanction direct third-party DB reads (schema drift) and write-by-commit
|
||||
timing. (T14, UC-68/76/79/81.)
|
||||
6. **Portable span address** across heterogeneous backends — wrap native IDs (Roam/Notion/
|
||||
CRDT UUID, Logseq `id::`, Trilium noteId, **Wikibase Q/P + stmt GUID**, fedwiki story-item
|
||||
id) in a shard-scoped address? (T16.)
|
||||
7. **CRDT shards** — embed a CRDT client (Yjs/Yrs) for a live replica, or consume snapshots?
|
||||
Overlays as CRDT ops or out-of-band patches? (T14, UC-64.)
|
||||
8. **Page model breadth** — can one model carry prose + typed/computed records +
|
||||
inline-embedded objects + typed-graph statements + non-MD assets + query-defined pages +
|
||||
multi-placement identity coherently? (T12.)
|
||||
9. **Whole-file & partial-history shards** — overlays against a whole-file shard
|
||||
(TiddlyWiki single-file: buffer+re-serialize vs require `.tid`); representing
|
||||
partial/truncated history (Oddmuse) with completeness metadata. (T11/T13, UC-78/82.)
|
||||
10. **Content opacity & lossy-exportable** — what is visible for an opaque/proprietary shard
|
||||
(IDs/structure vs nothing vs lossy HTML); never present a lossy export as faithful; does
|
||||
shard-wiki ever hold keys? (T11, UC-61/80.)
|
||||
|
||||
---
|
||||
|
||||
## 7. Sources
|
||||
|
||||
A synthesis; primary sources are the fourteen dives' `findings.md` files plus
|
||||
A synthesis; primary sources are the ~23 dives' `findings.md` files plus
|
||||
`research/260608-{federation-concepts,wikiengines-overview,c2-wiki-origins,yawex-prior-art}`.
|
||||
No new external research was performed in v2.
|
||||
No new external research was performed in v3 (it consolidates the WP-0003 batch dives
|
||||
260614-{federated-wiki,wikibase,forge-wikis,tiddlywiki,ikiwiki,quip,mojomojo,oddmuse,
|
||||
usemodwiki}).
|
||||
|
||||
Cross-references: `spec/UseCaseCatalog.md` (UC-26–UC-67),
|
||||
Cross-references: `spec/UseCaseCatalog.md` (UC-26–UC-82),
|
||||
`workplans/SHARD-WP-0002-federation-architecture.md` (T1–T16),
|
||||
`workplans/SHARD-WP-0003-engine-dives-batch.md` (the engine batch, done),
|
||||
`INTENT.md` (constraints), [[shard-wiki-auth-in-core-decision]].
|
||||
|
||||
---
|
||||
|
||||
## 8. Traceability
|
||||
|
||||
- Consolidates: all fourteen deep dives + federation/origin research into one capability
|
||||
model (v2).
|
||||
- Feeds: `SHARD-WP-0002` T11 (**thirteen-spectra** vocabulary, incl. content-opacity +
|
||||
merge-model), T12 (page-model breadth: computed metadata, identity≠placement, non-MD),
|
||||
T13 (history incl. CRDT-log = supplement), T14 (full attachment-mode taxonomy incl.
|
||||
CRDT-replica + P2P + interchange-mirror + local-REST), T15 (lossy incl. HTML), T16
|
||||
(addressing, content identity, identity≠placement, derived index, dimensional/query).
|
||||
- UC coverage extended in the workplan from UC-34–UC-59 to **UC-34–UC-67**.
|
||||
- No UCs added (synthesis only); no boundary changes (INTENT Stability Note untouched).
|
||||
</content>
|
||||
- Consolidates: all ~23 deep dives + federation/origin research into one capability model
|
||||
(v3 adds the WP-0003 batch).
|
||||
- Feeds: `SHARD-WP-0002` **T1–T6** (federation-model taxonomy §2.5 — selectable/composable
|
||||
federation), **T11** (**fourteen-spectra** vocabulary, incl. provenance granularity +
|
||||
expanded attachment modes + payload-format facet), T12 (page-model breadth: typed-graph,
|
||||
inline-embedded objects, computed metadata, identity≠placement, non-MD), T13 (history incl.
|
||||
DB-rows + partial-flat-file = supplement, completeness metadata, journal-shaped
|
||||
coordination journal), T14 (full attachment taxonomy incl. git-IS-store / container /
|
||||
direct-DB / REST-file-hybrid + source-of-truth per binding), T15 (lossy + not-Markdown
|
||||
graph/HTML), T16 (addressing incl. statement GUID + opaque stable identity, graph query /
|
||||
federated SERVICE).
|
||||
- UC coverage extended in the workplan from UC-34–UC-67 to **UC-34–UC-82**.
|
||||
- No UCs added (synthesis only); no boundary changes (INTENT Stability Note untouched —
|
||||
the federation-model taxonomy is a refinement of *how* the coordination layer works, not a
|
||||
redefinition of shard / Git's role / orchestrator-vs-engine).
|
||||
|
||||
@@ -22,7 +22,7 @@ when multiple files or sources are involved. Findings here inform `spec/` and
|
||||
| 2026-06-14 | `260614-roam-deep-dive/` | Roam Research — block-graph DataScript DB, transclusion, datalog, Roam Depot extension API; UC-50/51/52 |
|
||||
| 2026-06-14 | `260614-obsidian-deep-dive/` | Obsidian — file-over-app vaults, plugin API, ecosystem-popularity → UC signal; UC-53/54/55/56 |
|
||||
| 2026-06-14 | `260614-notion-deep-dive/` | Notion — closed block-DB SaaS, external REST API only, database-as-pages; UC-57/58/59 |
|
||||
| 2026-06-14 | `260614-shard-spectrum-synthesis/` | Synthesis — shard family matrix + eleven capability spectra across nine systems; feeds SHARD-WP-0002 T11–T16 |
|
||||
| 2026-06-14 | `260614-shard-spectrum-synthesis/` | Synthesis (v3) — shard family matrix + **fourteen** capability spectra across ~23 systems + **federation-model taxonomy** (fork+journal / VCS-replication+ping / query-join / engine-mirror); feeds SHARD-WP-0002 T1–T6 + T11–T16 |
|
||||
| 2026-06-14 | `260614-joplin-deep-dive/` | Joplin — SQLite-local/Markdown-on-sync, interchange-format attach, E2EE content opacity; UC-60/61 |
|
||||
| 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 |
|
||||
|
||||
Reference in New Issue
Block a user