shard-wiki/workplans/SHARD-WP-0002-federation-architecture.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	depends_on	state_hub_workstream_id
SHARD-WP-0002	workplan	federation architecture design	whynot	shard-wiki	done	tegwick	whynot	2026-06-08	2026-06-15	SHARD-WP-0001	2af4c46d-cbfd-40ea-a94b-d9e60b0f9945

SHARD-WP-0002 — Federation architecture design

Goal

Produce a federation architecture specification for shard-wiki: positioning against prior art (Federated Wiki, git-backed wikis, ActivityPub), documented decisions and tradeoffs, and ADR-ready design notes that resolve the open questions raised by research/260608-federation-concepts/ and UseCaseCatalog UC-26–UC-33.

Primary deliverable: spec/FederationArchitecture.md (created and filled by this workplan's tasks).

Secondary deliverable (T11–T16): the shard adapter contract constraints distilled from the engine deep dives (T11–T15, added 2026-06-13) and the modern-tool dives + cross-dive synthesis (T16 and scope extensions, added 2026-06-14), feeding spec/TechnicalSpecificationDocument.md. Federation architecture decides what the union does; the adapter contract decides what a backend must expose to participate. The two are co-dependent (the capability matrix T10 consumes the contract vocabulary T11 defines), so they live in one workplan.

Tertiary deliverable (T17–T18, added 2026-06-15): two selectable-axis deliverables re-folded from the later syntheses — T17 the federation-model taxonomy (federation is plural and composable, from synthesis v3) and T18 the computational / executable content capability (from the SHARD-WP-0004 "computational page model" synthesis).

The cross-dive synthesis (research/260614-shard-spectrum-synthesis/findings.md, v3 2026-06-14 — extended across ~23 systems incl. the SHARD-WP-0003 engine batch: Federated Wiki, Wikibase, the git-forge wikis, TiddlyWiki, ikiwiki, Quip, MojoMojo, Oddmuse, UseModWiki, on top of v2's Joplin/Logseq/CRDT-cohort/Trilium) reframes the contract around fifteen capability spectra — the thirteen of v2 (addressing, content identity, identity-vs-placement, structure, history, merge model, native query, translation, attachment mode, operational envelope, access grant, content opacity, write granularity) plus #14 provenance granularity (v3: per-shard → per-page → per-edit → per-statement/value) and #15 computational / liveness (SHARD-WP-0004: static → captured- output → live-over-files → view-time → irreducibly-live) — positions on a spectrum anchored at both ends by a real system, with federation ops degrading by position, rather than a flat verb checklist. v3 also adds a coordination-layer axis (the federation-model taxonomy, T17) and the computational page model adds a two-axis projection model (replication↔ derivation-projection × live↔snapshot, T16/T18).

Context

• Federation research: research/260608-federation-concepts/findings.md
• Engine deep dives (adapter-contract inputs, T11–T15):
  • research/260608-wikiengines-overview/findings.md (landscape; capability heterogeneity, write granularity)
  • research/260613-xwiki-deep-dive/findings.md (DB/component app-platform)
  • research/260613-twiki-deep-dive/findings.md (file+RCS app-platform)
  • research/260613-foswiki-deep-dive/findings.md (Foswiki::Store versioned store interface = adapter-contract prior art)
• Conceptual + modern-tool dives (T16 + scope extensions, 2026-06-14):
  • research/260614-xanadu-deep-dive/findings.md (reference-not-copy, transclusion, tumbler span addressing — ideal)
  • research/260614-zigzag-deep-dive/findings.md (information space as co-equal dimensions; clone = transclusion — ideal)
  • research/260614-roam-deep-dive/findings.md (block-DB, store UUIDs, Datalog, in-app host)
  • research/260614-obsidian-deep-dive/findings.md (file-over-app, in-file ^id, MetadataCache derived index, dual attach, ecosystem popularity)
  • research/260614-notion-deep-dive/findings.md (closed SaaS, external-API-only, DB schema+relations, operational envelope, scoped grant)
  • research/260614-joplin-deep-dive/findings.md (SQLite-local, interchange/sync-mirror attach, E2EE content opacity, local-REST)
  • research/260614-logseq-deep-dive/findings.md (block-graph on plain files, in-file id::, derived Datalog index, file→SQLite substrate migration)
  • research/260614-localfirst-workspaces-deep-dive/findings.md (Anytype/AFFiNE/AppFlowy: CRDT substrate, native merge, P2P/E2EE, CRDT-replica attach)
  • research/260614-trilium-deep-dive/findings.md (note cloning → DAG / identity≠placement, inherited+templated computed metadata, HTML-native, scripting+ETAPI, per-item opacity)
• Engine batch + federation-model inputs (T17 + spectra extensions, 2026-06-14, SHARD-WP-0003):
  • research/260614-federated-wiki-deep-dive/findings.md (fork+journal federation; story = semantic-action replay — the coordination-journal anchor)
  • research/260614-wikibase-deep-dive/findings.md (typed entity-statement graph; SPARQL + federated SERVICE = query-time graph-join federation; per-statement provenance/rank)
  • research/260614-forge-wikis-deep-dive/findings.md (Gitea/GitLab/GitHub: git IS the store — resolves the engine-mirror write-race; the home case)
  • research/260614-{tiddlywiki,ikiwiki,quip,mojomojo,oddmuse,usemodwiki}-deep-dive/findings.md (whole-file write-granularity; VCS-replication+ping federation; direct-DB binding; the flat-file floor)
• Computational / interactive-knowledge inputs (T18 + page-model/projection extensions, 2026-06-14/15, SHARD-WP-0004):
  • research/260614-{literate-programming,jupyter,mathematica,processing,strudel, squeak-pharo,glamorous-toolkit}-deep-dive/findings.md (one-source-many-projections; notebook computed-output provenance; program-as-page; live↔snapshot; moldable views; image-is-not-a-store)
  • research/260614-computational-page-model-synthesis/findings.md (the computational page model: source/derivation/projection, two axes, four page shapes, execution-as- gated-capability)
• Cross-dive synthesis: research/260614-shard-spectrum-synthesis/findings.md (synthesis v3: the fifteen capability spectra, shard family matrix across ~23 systems, the federation-model taxonomy §2.5, UC-34–UC-82 → task fold-in)
• Use cases: spec/UseCaseCatalog.md (UC-26–UC-84; UC-34–UC-43 engine-attachment, UC-44–UC-67 conceptual + modern-tool, UC-68–UC-82 engine-batch, UC-83–UC-84 computational)
• Aspiration: INTENT.md (orchestrator, not engine; mechanism over policy; capability-aware adapters; Markdown-first, backend-neutral)
• Related workplan: SHARD-WP-0001 (page resolution, namespaces, overlays, provenance — federation architecture must align with, not duplicate, those outputs)

Non-goal: Implement federation. This workplan produces architecture and decision records only.

Decision topics (overview)

Topic	Key tradeoff	Primary UCs
Orchestrator positioning	Adapter layer vs fedwiki-style homogeneous network	UC-02, UC-26
Remix primitives	Fork vs overlay vs import vs link-only	UC-04, UC-26, UC-29
Equivalent page identity	Title/path/alias/graph matching; chorus vs canonical	UC-27, UC-07
History model	Per-shard journal vs Git coordination journal vs both	UC-29, UC-33
Union composition	Server orchestrator vs client composition	UC-05, UC-27
Change notification	Git ping, ActivityPub, poll — adapter transports	UC-31
Space lifecycle	Permanent vs ephemeral; archive and carry-forward	UC-28, UC-30
Transclusion depth	Whole-page projection vs inline span	UC-03, UC-32
Consensus presets	Spread, merge, designated canonical — policy not core	UC-07, UC-27
Capability matrix	Which federation ops require which adapter capabilities	UC-02–UC-07
Federation-model taxonomy (T17)	Federation is plural & composable: fork+journal / VCS-replication+ping / query-time graph-join / feed-aggregation / activity-streams / engine-mirror — selectable, not one model	UC-26, UC-31, UC-33, UC-71, UC-72, UC-74

Adapter-contract topics (T11–T16, from engine + modern-tool dives)

Topic	Key tradeoff	Primary UCs
Adapter contract & capabilities	Thirteen spectra (not flat verbs); write granularity; operational envelope; access grant; merge model; content opacity	UC-02, UC-35, UC-38, UC-57, UC-61, UC-64
Structured page model	Typed frontmatter vs sidecar vs blob; bodiless / multi-record; DB schema+relations; computed (inherited/templated) metadata; non-Markdown assets; query-defined pages; multi-placement (DAG) identity	UC-34, UC-39, UC-55, UC-58, UC-54, UC-66, UC-67
History portability	Supplement (DB-internal incl. Notion/Joplin/Trilium; CRDT-log) vs import (open file history)	UC-36, UC-41
Adapter binding	Full mode taxonomy: file-store (native or interchange/sync-mirror) / in-engine-host / local-REST / external-API / CRDT-replica / P2P-no-central-endpoint; per-binding choice; backend-swap / substrate-migration	UC-38, UC-40, UC-43, UC-50, UC-57, UC-60, UC-62, UC-64, UC-65
Syntax translation	Lossless round-trip vs lossy-with-fidelity-report (HTML/blocks/CRDT) vs read-only degradation	UC-42, UC-59, UC-03
Addressing, identity & navigation (T16)	Span addressing; content identity; identity≠placement; transclusion-as-reference; derived query index; dimensional/query views; two-axis projection (replication↔derivation × live↔snapshot); moldable view registry	UC-44, UC-45, UC-46, UC-47, UC-48, UC-51, UC-52, UC-54, UC-63, UC-66, UC-83
Computational / executable content (T18)	Source canonical, render = projection; in scope as page-model+projection, out as execution platform; execute = gated capability, degrade to snapshot	UC-54, UC-55, UC-83, UC-84

---

Architecture positioning and boundaries

id: SHARD-WP-0002-T1
status: done
priority: high
state_hub_task_id: "ea8fdb22-6c7f-4ac1-9799-1346abf3c3b7"

Write the opening sections of spec/FederationArchitecture.md:

• shard-wiki as orchestration layer over heterogeneous shards (contrast Federated Wiki homogeneous JSON sites, ikiwiki homogeneous git wikis, ActivityPub activity streams).
• Explicit compare, do not equate mapping from federation research §6.
• Architectural boundaries: what core owns vs adapters vs UI vs policy config.
• Relationship to SHARD-WP-0001 outputs (resolution, namespaces, overlays).

Tradeoffs to document: Central Git coordination journal vs fully decentralized peer sync; browser-composed union vs server-side orchestrator for agents/CLI.

---

Remix primitives: fork, overlay, import, reference

id: SHARD-WP-0002-T2
status: done
priority: high
state_hub_task_id: "fb7d4bce-5d2e-4602-9b63-85934d90e82d"

Define when each remix primitive applies and how they interact:

Primitive	Typical trigger	Writes to remote?
Reference	Link only	No
Projection	Read remote page	No (cache optional)
Overlay	Edit read-only shard	No until explicit apply
Import / fork	Copy into writable shard	Source unchanged

Resolve federation research open question #1. Cover capability-limited shards (read-only, no diff/merge). Map to UC-26, UC-04, UC-29.

Tradeoffs: Fedwiki fork-as-default vs overlay-before-mutation; copy cost and attribution portability vs link-only federation.

---

Equivalent page identity and multi-version presentation

id: SHARD-WP-0002-T3
status: done
priority: high
state_hub_task_id: "8f2a333d-ddcc-4cc6-b6ed-1ba9b178eee3"

Specify how shard-wiki identifies "the same topic" across shards:

• Matching signals: normalized title, path, explicit alias table, link-graph equivalence, manual curator binding.
• Presentation: chorus-of-voices (UC-27) vs designated canonical (policy).
• Link to UC-07 divergence detection and reconciliation triggers.

Tradeoffs: Automatic matching false positives vs manual curation burden; showing all versions vs default canonical with alternates visible.

---

History, attribution, and coordination journal

id: SHARD-WP-0002-T4
status: done
priority: high
state_hub_task_id: "5f39f48d-5142-4078-a84f-3245ec1add7e"

Define how edit history and attribution flow across federation operations:

• Per-shard revision model (Git commit, engine history, fedwiki-style journal where applicable).
• Information-space coordination journal role for cross-shard operations (fork, import, reconcile, space branch).
• Portable attribution requirements for UC-29 (frictionless remix).

Tradeoffs: Fedwiki journal-per-page vs Git-only; duplication of history vs reconstructibility from coordination journal; storage cost of embedded media on import.

---

Union composition layer

id: SHARD-WP-0002-T5
status: done
priority: medium
state_hub_task_id: "3ff71e11-d0e9-4fda-b916-d6c34c51aa51"

Decide where the union view is assembled:

• Orchestrator API (server-side graph for agents, CI, non-browser clients).
• Optional client-side composition (fedwiki-style browser pull) as a consumer pattern, not the only path.
• Caching, freshness, and invalidation interaction with UC-03, UC-05, UC-31.

Tradeoffs: Single composition point (simpler provenance) vs distributed composition (fedwiki resilience); cache staleness vs live-pull latency.

---

Change notification and subscription transports

id: SHARD-WP-0002-T6
status: done
priority: medium
state_hub_task_id: "9596e5e8-8d6b-4ed4-bcbc-ebb45e3168be"

Specify change-notification as an optional adapter capability:

• Transports: git hook / pinger (ikiwiki), ActivityPub Create/Update (XWiki), WebDAV ETag, polling fallback.
• What a subscription triggers: projection refresh, reconciliation queue, RecentChanges union entry (UC-31, UC-17).
• Out-of-scope vs in-scope for v1.

Tradeoffs: Push freshness vs implementation complexity; ActivityPub as notification-only vs content-bearing share; dependency on external fediverse infrastructure.

---

Information space lifecycle

id: SHARD-WP-0002-T7
status: done
priority: medium
state_hub_task_id: "38134064-51ce-4f5a-80bf-b2cfbe381c59"

Model lifecycle states for root entities / information spaces:

• Active, read-only archived, retired (detached), merged-into-successor.
• Carry-forward workflow (UC-28, UC-30): selective import from archived shard.
• Space-level fork / branch (UC-33): coordination journal + shard config branch.

Tradeoffs: First-class ephemeral "happenings" vs permanent spaces only; automatic archive vs manual; whether retirement deletes projections or preserves read-only union entries.

---

Transclusion and projection depth

id: SHARD-WP-0002-T8
status: done
priority: medium
state_hub_task_id: "5607732b-612a-4550-bb17-b8cd34979cf4"

Distinguish projection levels:

Level	UC	Behavior
Whole-page projection	UC-03	Lazy full page from remote shard
Block/span transclusion	UC-32	Inline embed with origin + freshness
Link reference	UC-08	Pointer only

Define provenance display requirements and staleness semantics for UC-32. Reference Xanadu transclusion patterns without adopting unbuilt Xanadu scope.

Tradeoffs: Live transclusion fragility (link rot, remote down) vs snapshot on import; core orchestrator support vs Markdown extension + adapter.

---

Consensus and reconciliation policy catalog

id: SHARD-WP-0002-T9
status: done
priority: medium
state_hub_task_id: "adfca8b3-eb21-497d-9f51-65dc9269c810"

Document configurable policy presets (mechanism over policy):

• Fedwiki-spread (versions coexist; popularity implicit).
• Designated canonical shard (explicit write target).
• Git-merge reconciliation (ikiwiki-style).
• Overlay-only (no destructive merge on read-only sources).
• Vote-to-merge / editorial gate (optional, UI-layer).

Map presets to UC-07, UC-27. Core provides primitives; policy selects preset.

Tradeoffs: Default policy for L0 open mode vs team mode; exposing conflicts vs auto-merge when backends support it.

---

Federation operations capability matrix

id: SHARD-WP-0002-T10
status: done
priority: medium
state_hub_task_id: "c7a93d06-8631-43b4-bc7f-1b0a1cd1436f"

Produce a capability matrix: which federation operations require which adapter capabilities (read, write, diff, merge, lock, version, publish, notify, transclude-source).

Cross-check against INTENT capability-aware adapters principle. Identify graceful degradation paths for limited backends (read-only participant, projection-only, patch target).

This matrix consumes the capability vocabulary defined in T11 — keep the two in sync. Feeds spec/TechnicalSpecificationDocument.md adapter contract section.

---

Shard adapter contract (folded from engine deep dives, 2026-06-13)

These tasks distill the cross-cutting adapter-contract constraints surfaced by the four engine deep dives (wiki-engines landscape, XWiki, TWiki, Foswiki). They answer what a backend must expose to participate as a shard, complementing the federation tasks above (which answer what the union does). Output target: spec/TechnicalSpecificationDocument.md (adapter contract section), cross-linked from spec/FederationArchitecture.md.

Recurring cross-engine insight to honor: structure and history in text files federate far more easily than in a database, and Foswiki::Store already proves the versioned-interface-with-swappable-backends pattern the contract should adopt.

Adapter contract: capability model & versioned interface

id: SHARD-WP-0002-T11
status: done
priority: high
state_hub_task_id: "a7379621-6694-488b-94ca-846b8e27e745"

Define the capability-aware shard adapter contract as a versioned interface, taking Foswiki::Store + Foswiki::Meta as direct prior art (a real engine that already separates store backend from core behind a stable interface).

• Operation verbs: read, write, diff, merge, lock, version, publish, notify, transclude-source, translate-syntax, structured-payload, derive-projection, execute/evaluate (reconcile with T10; derive-projection/execute are gated, T18).
• Capability profile = the fifteen spectra (synthesis v3 §2 + SHARD-WP-0004), each a position not a boolean, so federation ops degrade by position:
  1. addressing granularity (none → path → page-level store id → in-file span → in-file block id:: → store-UUID → portable tumbler)
  2. content identity (none → path/title → fingerprint → span-set)
  3. identity vs placement (path=identity → identity separated from placement: Trilium note/branch; a page in many locations = a DAG)
  4. structure (flat MD → frontmatter/key:: → %META% → typed objects → DB schema+relations → object-graph/ontology → computed: inherited+templated)
  5. history (none → internal-only / CRDT-log → open-file → git-native)
  6. merge model (none → git/text → conflict-notes/keep-both → native-CRDT)
  7. native query (none → text → build-your-own derived index → datalog/graph → DB query)
  8. translation (native → lossless → lossy-with-fidelity-report; incl. HTML)
  9. attachment mode (file-store [native or interchange/sync-mirror] → in-engine-host → local-REST → external-API → CRDT-replica → P2P/no-central-endpoint)
  10. operational envelope (local/unbounded → realtime CRDT/WebSocket → rate-limited/ eventually-consistent/paginated)
  11. access grant (open → token → OAuth scoped+revocable → P2P key/invite)
  12. content opacity (plaintext → structured re-evaluable value [Wolfram expr] → encrypted-at-rest whole-shard → per-item → proprietary-lossy-exportable)
  13. write granularity (whole-file [TiddlyWiki] → per-page/note → section/anchor → per-block → story-item)
  14. provenance granularity (v3: per-shard → per-page → per-edit → per-statement/value, e.g. Wikibase claim references + rank)
  15. computational / liveness (SHARD-WP-0004: static source → captured-output snapshot → live-over-files → view-time render → irreducibly-live/temporal) — pairs with the T16/T18 projection axes
• Versioning/compatibility rules for the contract itself; capability discovery (static profile vs runtime negotiation).

Inputs: 260608-wikiengines-overview §3, §5; 260613-foswiki-deep-dive §2, §6; 260614-shard-spectrum-synthesis §2, §5 (v3 — fifteen spectra incl. provenance granularity + computational/liveness); 260614-wikibase-deep-dive (per-statement provenance/rank). Provides the vocabulary T10's matrix consumes; the computational/ execute capabilities are detailed in T18. UCs: UC-02, UC-35, UC-38, UC-57, UC-61, UC-64, UC-75, UC-83, UC-84.

Tradeoffs: Rich capability set (precise degradation) vs contract complexity; static profile vs runtime capability negotiation.

---

Page model: structured / typed payload representation

id: SHARD-WP-0002-T12
status: done
priority: high
state_hub_task_id: "7334a4a4-ba75-4fac-a8b4-8350d342b299"

Decide how the backend-neutral, Markdown-first page model carries structured data without flattening:

The model must stretch many ways at once (synthesis v2 §3): prose Markdown, typed and computed records, non-Markdown assets, reference/query-defined pages, and multi-placement (DAG) identity.

• Source shapes: XWiki XObjects against an XClass; TWiki/Foswiki DataForms stored as %META:FIELD% in text; Foswiki MetaDataPlugin multiple records per topic; Semantic MediaWiki annotations; Notion databases (schema + typed properties + inter-record relations + rollups/formulas) — the apex of database-as-pages.
• Representation choice: typed frontmatter vs sidecar file vs opaque provenance blob. Prefer in-text structure (frontmatter/%META%, git-diffable); tolerate DB structure via sidecar + fidelity report (T15).
• Bodiless pages (UC-39): may a page be purely structured, no Markdown body?
• N typed records per page (not one form) must be representable.
• Non-Markdown content types (UC-55): drawings (Excalidraw), spatial canvases (JSON Canvas), images, attachments — typed asset vs opaque blob vs content-type registry, with provenance, not flattened away.
• Inter-record relations (UC-58): represented as typed links in the union link graph, a separate relation index (cf. ZigZag many-to-many), or both (T16).
• Query-defined / reference pages (UC-44, UC-54): a page whose canonical form is a span manifest (Xanadu EDL) or a saved query (Dataview/Notion linked DB) — coordinate with T16.
• Computed metadata (UC-67): Trilium attributes are inherited (down the tree) + templated, so effective metadata = own + inherited + templated. Represent effective-vs-own with per-attribute provenance (own / inherited-from / template); decide materialize (snapshot) vs compute-live.
• Multi-placement / DAG identity (UC-66): Trilium note (identity) vs branch (placement) — a page may occupy several locations at once. Separate page identity from placement (one entity, N placements/paths/shards); no single canonical path — coordinate with T16 (the namespace-level clone/reference primitive).
• Typed-graph statements (UC-73): Wikibase claim + qualifiers + references + rank — the structure far-end (a true knowledge graph), beyond Notion DB / XWiki XObjects.
• Computational page shapes (UC-83, UC-84 — detailed in T18): the model must also carry (a) one-source-many-projections (literate source → co-equal derived views, UC-83); (b) notebook — ordered/nestable cells where code cells own embedded computed outputs (derived output stored inside the source) with weak provenance, outputs being MIME blobs or structured re-evaluable values (UC-84); (c) program-as-page (source text, no cached output); (d) live/temporal content (source + marked recording). All reduce to (source, derivation rule, projection with provenance + liveness).

Inputs: xwiki §2.3; twiki §2.3; foswiki §4; notion §2–§3; obsidian §3; trilium §2–§3; localfirst-workspaces §1–§3; wikibase §1; literate-programming; jupyter; mathematica; shard-spectrum-synthesis §3 (v3); computational-page-model-synthesis §3. UCs: UC-34, UC-39, UC-55, UC-58, UC-54, UC-44, UC-66, UC-67, UC-73, UC-83, UC-84.

Tradeoffs: Lossless fidelity vs a uniform queryable model; diff/search over structured fields vs prose; one coherent model vs many content shapes; effective-vs-own metadata snapshot vs live computation.

---

History portability: supplement vs import

id: SHARD-WP-0002-T13
status: done
priority: high
state_hub_task_id: "6837862a-8f57-410d-9200-a6a5dcf1a7b9"

Define how the coordination journal relates to an engine's native history (aligns with and refines T4):

History is a spectrum (synthesis v2 §2): none → internal-only / CRDT-log → open-file → git-native.

• Adopt — already git-native (Git folder/repo, Obsidian-with-Git, Logseq files): use as-is.
• Supplement — engine history is non-portable: DB-internal (Confluence, MediaWiki, XWiki xwikircs, Notion, Joplin/Trilium revisions) or a CRDT update log (Anytype/AFFiNE/AppFlowy): the journal begins now / mirrors forward / snapshots the replica (UC-36).
• Import — engine history is an open file format (TWiki/yawex RCS .txt,v, Foswiki PlainFile timestamped copies): backfill into Git preserving author/timestamp (UC-41).
• DB-version-rows (MojoMojo) — relational version rows as a third import source beside git commits and RCS files; partial/truncated flat-file history (Oddmuse keep/) must be reported honestly ("history begins at", UC-24), never implied complete.
• Embedded-output documents (notebooks, T18) — .ipynb JSON diffs are noisy; record text-pairing (Jupytext) / cell-aware merge (nbdime) and the outputs-as-derived (nbstripout) stance as the history-portability strategy for source-with-embedded-output.
• Authoritative journal vs mirror-reconciled-back; one-time vs continuous.

Inputs: xwiki §2.4; twiki §2.1; foswiki §2.2; notion §4; joplin §1; trilium §1; localfirst-workspaces §4; mojomojo §1, §4; oddmuse §2; jupyter §3. UCs: UC-36, UC-41, UC-24.

Tradeoffs: Import fidelity vs effort; duplicated history vs single source of truth.

---

Adapter binding: attach path, hosting, backend-swap

id: SHARD-WP-0002-T14
status: done
priority: medium
state_hub_task_id: "f8835969-d118-4738-952a-5e67e5209f3d"

Decide how and where an adapter binds to a backend:

Full attachment-mode taxonomy (synthesis v2 §2, §3), with a backend possibly offering more than one — so attach mode is a per-binding, capability-gated choice, not a fixed property:

• File-store direct — read the on-disk store as a folder shard, in two sub-kinds:
  • native store — Obsidian vault, Logseq pages/+journals/ (with a format profile parsing id::/key::), TWiki data/, Git repo: offline, git-native, but risks inconsistent reads under a running engine (UC-40, UC-53, UC-62).
  • interchange / sync mirror — a tool's documented sync representation on a third-party target (Joplin items on WebDAV/Nextcloud/S3): app-independent, read/projection/ overlay-mostly (the tool owns the format; never re-sync) (UC-60).
• In-engine hosted adapter — adapter runs inside the app via its extension API (XWiki components; TWiki/Foswiki handlers; Roam Depot over roamAlphaAPI; Obsidian plugin over App.vault; Logseq plugin; Trilium scripting code notes): high fidelity, needs deploy access (UC-38, UC-50).
• Local-REST — a localhost API served by the running app (Joplin Data API; Trilium ETAPI): app-must-run, token auth (UC-38, links UC-57).
• External-API only — attach from outside via a remote REST API, no in-engine hosting (Notion): full write-through without deploy access, but bounded by the operational envelope (rate limit, eventual consistency, payload caps) and a scoped, revocable access grant that enforces no-silent-mutation (UC-57).
• CRDT replica — hold a local CRDT replica (Anytype/AFFiNE/AppFlowy: any-sync/ Yjs/Yrs): the backend merges natively — respect CRDT semantics, don't git-merge; or a self-host sync endpoint (AFFiNE/AppFlowy Cloud) (UC-64).
• P2P / no-central-endpoint — bind a replica or a named peer/node, not a URL (Anytype any-sync), content possibly E2EE (UC-65).
• Dual / multi attach — a backend offering several modes (Obsidian/Logseq: file or plugin; TWiki: file or API; Joplin: mirror or Data API): pick per binding; declare which is authoritative (UC-53).
• Git-IS-the-store (forge wikis Gitea/GitLab/GitHub, ikiwiki) — the wiki is a .wiki.git / source repo of Markdown; git-clone is universal and git is the canonical store and journal at once (the home case; resolves the engine-mirror write-race — bind to git, not to a DB-mirror) (UC-76, UC-79).
• Direct-DB read (MojoMojo) — no file store and no API; the adapter maps a relational schema → page model + journal (a versioned coupling that can drift, UC-43); default read/projection/overlay (UC-81).
• Backend-swap / substrate-migration tolerance — shard identity/provenance survives a storage change (Foswiki RCS↔PlainFile; folder→Git; Logseq file→SQLite DB-graph) — bind to capabilities, not to "it's files" (UC-43).
• Boundary — image-is-not-a-store (Squeak/Pharo, T18): a monolithic live-memory blob (image, kernel) is never an attach target; it participates only via export→files (a degrading derivation-projection). Generalizes "attach the files, not the kernel/image" (notebooks UC-84, GT/Lepiter).

Inputs: twiki §5–§6; xwiki §3; foswiki §2; roam §5; obsidian §4; notion §4, §6; joplin §2, §4; logseq §4–§5; localfirst-workspaces §4; trilium §5; forge-wikis; ikiwiki §1; mojomojo §2; squeak-pharo §2–§3; shard-spectrum-synthesis §3 (v3). UCs: UC-38, UC-40, UC-43, UC-50, UC-53, UC-57, UC-60, UC-62, UC-64, UC-65, UC-76, UC-79, UC-81.

Tradeoffs: Fidelity vs deploy access; consistency vs offline capability; external write-through vs rate-limit/eventual-consistency ceiling; CRDT-replica liveness vs snapshot simplicity.

---

Syntax translation & content fidelity

id: SHARD-WP-0002-T15
status: done
priority: medium
state_hub_task_id: "22b57b3a-b06b-4ff0-a34a-667a0386bf25"

Specify how non-Markdown shards participate in the Markdown-first model:

Translation is a spectrum (synthesis §2): native → lossless → lossy-with-fidelity-report.

• Read native markup (TWiki/Foswiki TML, XWiki syntax) into the page model and accept Markdown overlays back via bidirectional, lossless translation (UC-42).
• Feasibility proof: Foswiki WysiwygPlugin (TML→HTML for editing, HTML→TML losslessly on save).
• Lossy-with-fidelity-report (UC-59) — for models that do not round-trip: Notion blocks/rich-text/databases (export is lossy); Trilium HTML (CKEditor — more tractable than blocks but still lossy); CRDT/object models. Translate lossily but make fidelity loss visible — a per-shard/per-page report of what projects cleanly vs. degrades, with non-mappable elements preserved as provenance/sidecar. Fidelity becomes data (union without erasure). Distinct from the lossless case (UC-42).
• HTML as a source model (Trilium) joins TML/Notion-blocks/CRDT in the translation capability — HTML↔Markdown, lossy-aware.
• Typed-graph & non-Markdown computed content (T18): Wikibase statements (UC-73), notebook MIME-bundle outputs, and .ipynb/.nb JSON are not Markdown — keep the native form canonical, treat any Markdown as a lossy projection; add a structured re-evaluable value point to the opacity spectrum (Wolfram expression) between transparent-text and opaque-blob.
• Graceful degradation: when neither lossless nor acceptable lossy translation is available, the shard is a read-only/projection participant (UC-03), never silently corrupted.
• Open: may overlays be stored in Markdown, or must they round-trip in native syntax?

Inputs: foswiki §5; twiki §2.4; xwiki §2.5; notion §3; trilium §4. UCs: UC-42, UC-59, UC-03.

Tradeoffs: Translation coverage vs read-only floor; Markdown overlays (portable) vs native-syntax overlays (safe round-trip); lossy-but-usable vs read-only-but-faithful.

---

Addressing, content identity, and dimensional / query navigation

id: SHARD-WP-0002-T16
status: done
priority: medium
state_hub_task_id: "b00ca669-59d6-454a-8d6e-f34694e35192"

New thread from the conceptual (Xanadu, ZigZag) + modern-tool (Roam, Notion, Obsidian/ Dataview) dives and the synthesis (260614-shard-spectrum-synthesis §4). No existing task owns the addressing/identity/navigation layer that transclusion, overlay, equivalence, and dimensional views depend on. Refines T8 (transclusion/projection depth) and T5 (union composition); consumes T11 capabilities.

• Span addressing — a portable sub-page address. Adopt native span IDs where the backend mints them (Roam :block/uid, Notion/CRDT UUID, Joplin/Trilium page-level id) or carries them in-file (Obsidian ^id, Logseq id:: — block-level AND git-diffable, the sweet spot); fall back to content fingerprint or path+range otherwise. Open: wrap native IDs in a shard-scoped address so they survive projection and don't collide across shards (Xanadu tumbler is the unreached ideal). (UC-51, UC-44.)
• Content identity — detect that two pages are the same / derived content by fingerprint or span-set overlap, path-independently — the equivalence mechanism UC-27 left open. Enables reverse transclusion (UC-45). (UC-46.)
• Identity vs placement — separate page identity from placement (Trilium note vs branch: a page cloned into many locations = a DAG). One entity, N placements (paths/ shards); no single canonical path — the namespace-level form of the clone/reference primitive. (UC-66, UC-22.)
• Transclusion as one reference-not-copy primitive — unify Xanadu transclusion, ZigZag clone, Roam/Obsidian/Logseq embed, Notion synced block, Trilium note cloning, and literate named-chunk assembly (<<name>> resolved by name at derivation time, UC-83) over the addressable union (synthesis v3 §3). Compose-by-reference pages (UC-44) and reverse lookup (UC-45) are views over it.
• Two-axis projection model (T18, the computational page model): split projection into replication-projection (lazy cache of remote content — the current default) vs derivation-projection (transform/compile/weave/evaluate a source), with facets materialization timing (ahead-of-time vs view-time), multiplicity (one output vs N co-equal projections), and continuity (one-shot vs continuous); crossed with the live↔snapshot axis (static → captured → live-over-files → view-time → irreducibly-live). Every computed/live view declares its liveness + provenance; the far end has no faithful static form (source + marked recording).
• Moldable view registry (Glamorous Toolkit) — generalize "a projection" to an open, type-keyed set of co-equal, possibly-computed views, none canonical (display-canonical is policy). Unifies replication-/derivation-/dimensional-(ZigZag)/query-(Dataview) projection and answers UC-55's pluggable-content-type/view-registry question. (UC-47, UC-48, UC-54.)
• Dimensional / query navigation — model the union so each relationship (namespace, genealogy, version, shard, equivalence, links) is a navigable dimension (ZigZag), and a page can be query-defined (Dataview/Notion linked DB, UC-54). Delegate view computation to a shard's native query engine where present (Roam/Logseq Datalog, Notion/AppFlowy DB query, XWiki XWQL); else build a derived index over the projection (Logseq DataScript-over-files pattern, UC-63). (UC-47, UC-48, UC-52, UC-54, UC-63.)
• Boundary: this is a derived lens over canonical files+journal, never a new store (ZigZag dive §6); the many-to-many link graph stays a graph index, not a rank.

Inputs: xanadu §2–§5; zigzag §2–§6; roam §2–§4, §7; notion §2; obsidian §2–§3; logseq §1–§3; trilium §2–§3; wikibase (federated SERVICE / graph query); literate-programming; glamorous-toolkit; shard-spectrum-synthesis §3–§5 (v3); computational-page-model-synthesis §2. UCs: UC-44, UC-45, UC-46, UC-47, UC-48, UC-51, UC-52, UC-54, UC-63, UC-66, UC-74, UC-83.

Tradeoffs: Native-ID adoption (cheap, backend-coupled) vs a portable address scheme (harder, uniform); core navigation API vs internal organizing concept; query delegation (fast, backend-dependent) vs orchestrator-computed (uniform, costly).

---

Re-folded syntheses (2026-06-15)

These two tasks re-fold the later syntheses — synthesis v3 (the federation-model taxonomy) and the SHARD-WP-0004 "computational page model" — into this workplan as selectable-axis deliverables. T17 is a federation-architecture concern (cross-links T1–T6); T18 is an adapter-contract concern (cross-links T11–T16).

Federation-model taxonomy: selectable / composable federation

id: SHARD-WP-0002-T17
status: done
priority: high
state_hub_task_id: "529b32d2-b681-4711-82c5-5298410cfb37"

Specify federation as a plural, composable coordination-layer axis rather than a single model (synthesis v3 §2.5). Document each model, its capability prerequisites, and how shard-wiki selects/composes them per information space:

Model	Anchor system	Coordination shape	Primary UCs
Fork + journal	Federated Wiki	copy-with-provenance + per-page semantic-action journal (story = replay)	UC-26, UC-71, UC-72
VCS-replication + ping	ikiwiki	git clone/pull/push + XML-RPC change-ping	UC-31, UC-33, UC-79
Query-time graph-join	Wikibase SPARQL SERVICE	join remote graphs at query time, no copy	UC-74
Feed aggregation	RSS/Atom (ikiwiki aggregate)	inbound feed → pages	UC-03
Activity streams	ActivityPub	Create/Update events as notification or content-bearing share	UC-31
Engine-mirror	Wiki.js (DB↔Git)	engine syncs its own store to a git mirror	UC-68, UC-69

• The coordination journal (T4) is the fork+journal model's natural home; git IS the journal in VCS-replication and engine-mirror (forge wikis make git the store and journal at once, resolving the engine-mirror write-race — git-IS-store, T14).
• Models are selectable per space and composable (e.g. fork+journal locally, query-join for a typed-graph shard, feed-aggregation for an external source) — mechanism over policy.
• Cross-link: T1 (positioning names the taxonomy), T2 (fork is one remix primitive among many), T4 (journal shapes), T5 (composition), T6 (notification transports).

Inputs: federated-wiki (fork/journal); ikiwiki §2 (VCS-replication+ping, aggregate); wikibase (federated SERVICE); wikijs (engine-mirror); 260608-federation-concepts; shard-spectrum-synthesis §2.5 (v3). UCs: UC-26, UC-31, UC-33, UC-68, UC-69, UC-71, UC-72, UC-74, UC-79.

Tradeoffs: One uniform model (simpler) vs plural/composable (faithful to heterogeneity); query-time join freshness vs cost; activity-streams reach vs fediverse dependency.

---

Computational / executable content capability

id: SHARD-WP-0002-T18
status: done
priority: medium
state_hub_task_id: "331c2a9b-57bb-4067-8d1f-9a3de10e2873"

Specify how shard-wiki treats computational / executable / live page content, re-folded from the SHARD-WP-0004 computational page model synthesis. Headline decision to record: computational content is IN scope as a page-model + projection concern, OUT of scope as an execution platform.

• The model: source is canonical; everything rendered/computed is a projection placed on two axes (replication↔derivation × live↔snapshot, defined in T16). Four computational page shapes (detailed in T12): one-source-many-projections (UC-83), notebook with embedded computed-output provenance (UC-84), program-as-page, live/temporal content.
• Recognition + projection, not execution: shard-wiki recognizes computational types, attaches the canonical source, and presents derived forms as provenance- and liveness-marked projections — needing no kernel/sandbox/runtime for the base case.
• Execution as a gated capability (T11 derive-projection/execute verbs): driving a derivation (tangle/weave, re-execute a notebook, render a sketch, evaluate a pattern in the viewer) is off by default, carries a trust/sandbox sub-concern, and degrades to a captured snapshot / static render / recording when absent (graceful degradation).
• One snapshot-provenance record reused for notebook outputs, renders, and recordings (run id, source rev, timestamp, environment "unguaranteed") — reuses UC-84 machinery and is consistent with partial-history honesty (UC-82).
• Hard boundaries (design-bugs if violated): never host a kernel/runtime as the store (image-is-not-a-store, T14); never present a derivation without output→source provenance; never imply a static view captures a live artifact (union without erasure).
• No INTENT amendment required — this extends the page model (T12) and projection model (T16) within existing constraints (mechanism over policy, capability-aware, degradable).

Inputs: the seven SHARD-WP-0004 dives (literate-programming, jupyter, mathematica, processing, strudel, squeak-pharo, glamorous-toolkit); computational-page-model-synthesis §1–§6. Feeds T11 (verbs + spectra #12/#15), T12 (page shapes), T13 (paired-text history), T14 (image-is-not-a-store), T15 (non-Markdown computed content), T16 (two-axis projection + moldable views). UCs: UC-54, UC-55, UC-83, UC-84.

Tradeoffs: Recognize-only (safe, limited) vs sandboxed execution (rich, complex/risky); live render fidelity vs snapshot simplicity; per-shard execute policy vs global off-by-default.

---

Acceptance criteria

• spec/FederationArchitecture.md exists with all ten federation topic sections (T1–T10) and an explicit decisions / deferred / open table per topic.
• The adapter contract section of spec/TechnicalSpecificationDocument.md exists, populated by T11–T16 + T18, with the capability vocabulary (T11, the fifteen spectra) reconciled against the T10 federation-ops matrix.
• The federation-model taxonomy (T17) is documented in spec/FederationArchitecture.md as a selectable/composable coordination-layer axis cross-linked from T1–T6.
• The computational page model (T18) is recorded with its headline decision (in scope as page-model+projection, out as execution platform; execute = gated capability).
• Each decision honors INTENT: mechanism over policy, union without erasure, overlay before mutation, no silent remote mutation, shard sovereignty, capability-aware adapters, Markdown-first / backend-neutral.
• UC-26–UC-84 are traceable to architecture / adapter-contract sections (UC-34–UC-43 to T11–T15; UC-44–UC-82 to T11–T17; UC-83–UC-84 to T18; per research/260614-shard-spectrum-synthesis/findings.md §4 (v3) and research/260614-computational-page-model-synthesis/findings.md §6).
• Conflicts or dependencies on SHARD-WP-0001 outputs are listed (e.g. namespace model affects equivalent-page identity; page model T12 affects resolution/overlays).
• SHARD-WP-0001 and SHARD-WP-0002 can proceed in parallel where topics are independent; merge conflicts in spec are resolved before implementation workplan starts.

Suggested task order

Federation architecture (T1–T10):

1. T1 positioning (frames everything)
2. T2 remix primitives + T3 equivalent identity (parallel)
3. T4 history model
4. T5 composition + T6 notification (parallel)
5. T7 lifecycle + T8 transclusion (parallel)
6. T9 policy catalog + T10 capability matrix (parallel, finalize doc)

Adapter contract (T11–T16) — can start in parallel with T1; T11 first as it frames the rest, and pair it with T10 (shared capability vocabulary): 7. T11 contract & the fifteen capability spectra (frames T12–T16; sync with T10) 8. T12 page model + T13 history portability (parallel; T13 aligns with T4) 9. T14 binding + T15 syntax translation (parallel) 10. T16 addressing, identity & navigation + the two-axis projection model (refines T8/T5)

Re-folded syntheses (T17–T18): 11. T17 federation-model taxonomy (with T1; cross-links T2/T4/T5/T6) 12. T18 computational / executable content (after T11/T12/T16; finalize adapter-contract spec)