diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index 1b3c3d8..f3557e0 100644 --- a/spec/UseCaseCatalog.md +++ b/spec/UseCaseCatalog.md @@ -34,11 +34,20 @@ Each use case lists: Priority hints: **MVP** = likely early value; **Later** = important but not first slice. +UC numbers are **stable identifiers**, not an ordering — they are assigned in discovery +order and referenced across `research/`, the synthesis, and the workplans, so they are +never renumbered. The catalog is organized **thematically** into seven sections: +**A** information space, federation & coordination · **B** shard attachment & adapter +binding · **C** page model, structure & content fidelity · **D** addressing, identity & +query · **E** knowledge work & collaboration · **F** discovery & navigation · **G** +provenance & page metadata. (Sections A–D are the orchestration/adapter surface — the bulk +of the shard-spectrum work; E–G carry the c2/yawex authoring and reading patterns.) + --- -## A. Information space and federation +## A. Information space, federation & coordination -*shard-wiki orchestration scenarios (INTENT + yawex federation seeds).* +*Federation, union, overlay, projection, and the Git-backed coordination layer (INTENT + yawex/federation seeds).* ### UC-01 — Standalone open wiki (L0) @@ -52,6 +61,8 @@ a living minimal instance — one CGI script, open editing, plain-text files (UC standalone open wiki can sit on. **Priority:** MVP +--- + ### UC-02 — Attach a shard to an information space **Actor:** Maintainer @@ -65,6 +76,8 @@ CRDT-replica (UC-64), P2P (UC-65), and — for a **DB-backed engine with no file `research/260614-mojomojo-deep-dive/findings.md` §2). **Priority:** MVP +--- + ### UC-03 — Project a remote shard page locally **Actor:** Reader @@ -75,6 +88,8 @@ provenance and freshness visible. mutation. **Priority:** Later +--- + ### UC-04 — Overlay edit on read-only shard **Actor:** Author @@ -85,6 +100,8 @@ before destructive apply. Overlay-before-mutation principle. **Priority:** Later +--- + ### UC-05 — Union derived views **Actor:** Reader @@ -100,6 +117,8 @@ navigable via UC-47 (`research/260614-zigzag-deep-dive/findings.md` §5). Note: many-to-many link/backlink graph stays a **separate graph index**, not a zz-rank. **Priority:** Later +--- + ### UC-06 — Authenticated team wiki (L2+) **Actor:** Authenticated principal @@ -116,6 +135,8 @@ delegated auth modules (`research/260614-wikijs-deep-dive/findings.md` §4) — should **honor/surface restricted regions**, not silently drop or expose them. **Priority:** Later +--- + ### UC-07 — Detect and reconcile cross-shard divergence **Actor:** Maintainer @@ -126,6 +147,8 @@ reconcile them under explicit policy. UC-27 (multi-version view) and SHARD-WP-0002 consensus-policy task. **Priority:** Later +--- + ### UC-26 — Fork page from remote shard into writable shard **Actor:** Author @@ -144,6 +167,8 @@ site**, and a forked journal stays **detailed enough to locate the upstream cut- carry-forward/re-fork (UC-28) and modelling the genealogy edge as **provenance** (UC-71/72). **Priority:** Later +--- + ### UC-27 — View multiple versions of equivalent page **Actor:** Reader @@ -157,6 +182,8 @@ detection mechanism via content-identity / span-set intersection (UC-46, detection. **Priority:** Later +--- + ### UC-28 — Carry forward pages from closed or archived shard **Actor:** Maintainer or author @@ -169,6 +196,8 @@ lifecycle policy. Complements UC-02 attach and UC-26 fork at scale. Obsidian's for importing from foreign tools (`research/260614-obsidian-deep-dive/findings.md` §7). **Priority:** Later +--- + ### UC-29 — Remix with portable attribution **Actor:** Author @@ -184,6 +213,8 @@ authz-in-core L0→L4 ladder decision. Remix should also record a **genealogy ed (UC-49) so reuse lineage is navigable, not just attributed. **Priority:** Later +--- + ### UC-30 — Time-bounded collaboration space **Actor:** Facilitator @@ -194,6 +225,8 @@ subset, then archive it while allowing selective carry-forward. coded core behavior. Relates to UC-28. **Priority:** Later +--- + ### UC-31 — Subscribe to remote shard changes **Actor:** Maintainer or reader @@ -216,24 +249,7 @@ mesh** (UC-79, `research/260614-ikiwiki-deep-dive/findings.md` §2), the federat beside fedwiki fork/journal (UC-72) and Wikibase `SERVICE` (UC-74). **Priority:** Later -### UC-32 — Transclude remote span with live freshness - -**Actor:** Author or reader -**Goal:** Embed a portion of a remote page inline with visible origin and -refreshable content. -**Source:** federation, intent -**Notes:** Xanadu transclusion pattern; stronger than UC-03 whole-page -projection. Provenance and staleness must be explicit. Xanadu deep dive sharpens this: -transclusion should be **content-identity based and bidirectional** (content is "knowably -in more than one place" and aware of its appearances), not a one-way path fetch — -enables UC-45 reverse lookup (`research/260614-xanadu-deep-dive/findings.md` §4). See -UC-44 for the whole-page composition-manifest form. **Roam ships this**: block embeds -transclude by `:block/uid` live (not copied), proving transclusion is a cheap data-layer -capability over an addressable store (`research/260614-roam-deep-dive/findings.md` §3, -§7) — argues for transclusion in core over the union, surfaced by UI. Depends on span -addressing (UC-51). **Logseq** does the same on *files*: `{{embed ((uuid))}}` transcludes -by an in-file block ID (`research/260614-logseq-deep-dive/findings.md` §2). -**Priority:** Later +--- ### UC-33 — Git-branch an information space @@ -245,38 +261,65 @@ divergent information space without destroying the original. Space-level fork — distinct from UC-26 page-level fork. **Priority:** Later -### UC-34 — Attach a structured or semantic shard without lossy flattening +--- + +### UC-56 — Publish a curated projection to an external read-only target **Actor:** Maintainer -**Goal:** Attach an engine whose pages carry structured or queryable data beyond -Markdown (Semantic MediaWiki annotations, XWiki objects/forms) and project it -without silently discarding the structure. -**Source:** wikiengines, intent -**Notes:** Engine scan shows "wiki page" spans flat Markdown to queryable -knowledge objects. Markdown-first must **degrade gracefully**, not flatten: -needs a passthrough / sidecar-metadata / provenance escape hatch. Page-model -question deferred to `SHARD-WP-0002` (findings §6 Q1). Distinct from UC-02 -(assumes Markdown-shaped pages). XWiki is the concrete exemplar: pages carry typed -XObjects against an XClass schema (`research/260613-xwiki-deep-dive/findings.md` -§2.3); UC-39 covers the extreme where the page is *only* structure. TWiki shows the -**git-friendly** variant: TWiki Forms store fields as `%META:FIELD%` *inside the -topic text file*, so structure is diffable rather than locked in a DB -(`research/260613-twiki-deep-dive/findings.md` §2.3). Roam is the modern exemplar: -`key:: value` attributes over a datom graph, queryable via Datalog -(`research/260614-roam-deep-dive/findings.md` §3, §4) — structure to preserve via -sidecar metadata, and a candidate for query delegation (UC-52). Obsidian shows the -**git-diffable in-file** variant: YAML frontmatter/properties live in the Markdown text -and are queried by the Dataview plugin (`research/260614-obsidian-deep-dive/findings.md` -§3) — structure as portable text, not DB state. **Notion** is the apex of the DB-locked -end: typed database properties with relations/rollups/formulas, lossy to Markdown — -see UC-58 (`research/260614-notion-deep-dive/findings.md` §2). **Logseq** sits between: -`key:: value` block/page properties live in the Markdown text (git-diffable) yet are -queried via a derived Datalog graph (`research/260614-logseq-deep-dive/findings.md` §2–§3) -— in-text structure at block granularity. **Trilium** adds **computed** structure: labels -+ typed relations that are **inherited + templated**, so effective metadata ≠ stored -metadata — see UC-67 (`research/260614-trilium-deep-dive/findings.md` §3). +**Goal:** Publish a selected projection of the union (or a shard) to an external +read-only target — a static site or hosted page set — preserving provenance. +**Source:** obsidian, intent +**Notes:** The Obsidian Publish / **Quartz** / Digital Garden pattern — outbound +publish (`research/260614-obsidian-deep-dive/findings.md` §7, §10). Formalizes the +`publish` capability from INTENT's adapter-capability list; **complements UC-37** +(inbound static-export *attach*) as its outbound mirror. Open: core vs. publish-adapter +family; interaction with overlays and projection freshness (findings §11 Q4). **Notion** +adds the closed-SaaS instance: **publish-to-web** renders pages as read-only public +pages (`research/260614-notion-deep-dive/findings.md` §4). **Priority:** Later +--- + +### UC-71 — Coordination journal as an append-only semantic-action log with provenance + +**Actor:** Core orchestrator +**Goal:** Model the coordination journal as a **per-page append-only log of semantic +actions** (`create`/`add`/`edit`/`move`/`remove`/`fork`) carrying **provenance entries** +(fork records the source site), with the page state **derived by replaying** the log and +divergence **located by comparing** logs. +**Source:** federation, intent +**Notes:** Directly adopts the fedwiki **journal** shape — the story is a materialized +view of the journal, fork entries serialize a **provenance DAG**, and per-entry sequence +numbers make the fork cut-point identifiable +(`research/260614-federated-wiki-deep-dive/findings.md` §2, §6). This is concrete prior art +for INTENT's coordination journal: a **third merge model** beside git 3-way and CRDT +auto-merge — a coarse semantic op-log applied manually via fork. Feeds SHARD-WP-0002 T13 +(history portability / merge model) and T1–T5 (federation). +**Priority:** Later + +--- + +### UC-72 — Federate by fork-with-provenance across a neighborhood / chorus + +**Actor:** Reader / curator +**Goal:** Assemble a **union from sovereign peer shards** discovered by **link and fork** +(a *neighborhood*) or by an explicit **roster**, **search across that set**, and preserve a +**chorus of co-equal, provenance-linked versions** without forcing a canonical — pulling +another's changes by forking them. +**Source:** federation, intent +**Notes:** Fedwiki's neighborhood (dynamic, link/fork-discovered) vs roster (curated) +membership and "chorus of voices" no-canonical stance +(`research/260614-federated-wiki-deep-dive/findings.md` §3, §4) model +**union-without-erasure** at the coordination layer: divergence is normal and visible, +reconciliation is an explicit human/policy step (mechanism over policy). Open: does a +chorus compose with shards that assert a canonical? Feeds SHARD-WP-0002 T1–T5; relates +UC-05/UC-27 (union/chorus), UC-26 (fork). +**Priority:** Later + +## B. Shard attachment & adapter binding + +*How heterogeneous backends attach — attachment modes, capability profile, history portability, and access — across the shard-spectrum synthesis.* + ### UC-35 — Attach a shard with coarse write granularity **Actor:** Maintainer @@ -297,6 +340,8 @@ engine* sits at both ends by substrate (UC-78, `research/260614-tiddlywiki-deep-dive/findings.md` §1, §3; cf. UC-43/UC-62). **Priority:** Later +--- + ### UC-36 — Supply a git-addressable history to an internal-history engine **Actor:** Maintainer @@ -327,6 +372,8 @@ engine's history **is** git even though its canonical store is a DB (UC-68, `research/260614-wikijs-deep-dive/findings.md` §2). **Priority:** Later +--- + ### UC-37 — Attach a static engine export as a read-only backup shard **Actor:** Maintainer @@ -340,6 +387,8 @@ UC-28 (carry pages *forward* into a new space); here the dump itself is the shard. Read-only mode in `spec/ArchitectureBlueprint.md`. **Priority:** Later +--- + ### UC-38 — Make a wiki engine federation-capable via its native extension API **Actor:** Engine developer / integrator @@ -374,23 +423,7 @@ prior art** (versioned, multi-provider Git/FS/S3/Azure, backup-or-source-of-trut (`research/260614-wikijs-deep-dive/findings.md` §2, §8). **Priority:** Later -### UC-39 — Attach a wiki-as-application-platform shard (pages as typed records) - -**Actor:** Maintainer -**Goal:** Attach an engine where pages are structured records or forms with little -or no prose body (XWiki AppWithinMinutes apps / XObjects), and represent them in the -union without inventing a fake Markdown body. -**Source:** wikiengines, intent -**Notes:** The extreme of UC-34 — not *annotations on prose* but **bodiless -structured pages**. Forces the question: does the page model require a Markdown body, -or can a page be purely typed data (`research/260613-xwiki-deep-dive/findings.md` -§8 Q2)? Affects union views, diff, and search. Deferred to `SHARD-WP-0002`. -Foswiki shows a middle point: MetaDataPlugin stores **multiple** structured records -per topic, still as `%META%` in text (`research/260613-foswiki-deep-dive/findings.md` -§4) — the page model must allow N typed records, not one form. **Notion** pushes -further: a *database* is a collection with a schema whose rows are pages joined by typed -relations — see UC-58 (`research/260614-notion-deep-dive/findings.md` §2). -**Priority:** Later +--- ### UC-40 — Attach a file-backed engine's on-disk store directly @@ -420,6 +453,8 @@ ideal engine-maintained file-store attach — see UC-68 (`research/260614-wikijs-deep-dive/findings.md` §2). **Priority:** Later +--- + ### UC-41 — Import an engine's native file history into the coordination journal **Actor:** Maintainer @@ -434,27 +469,7 @@ is the imported history authoritative or a one-time backfill (INTENT *History as the safety net*). **Priority:** Later -### UC-42 — Read and write a non-Markdown shard via lossless syntax translation - -**Actor:** Author or maintainer -**Goal:** Attach a shard whose native markup is not Markdown (TWiki/Foswiki TML, -XWiki syntax) and read it into the Markdown-first model — and write Markdown overlays -back — through **bidirectional, lossless syntax translation**, instead of treating it -as read-only. -**Source:** wikiengines, intent -**Notes:** Realizes *Markdown-first, backend-neutral* for **prose** (UC-34/39 cover -*structure*). Feasibility proven by Foswiki's **WysiwygPlugin** (TML→HTML for editing, -HTML→TML losslessly on save) (`research/260613-foswiki-deep-dive/findings.md` §5). -Open: is round-trip lossless enough, or must overlays be stored in the shard's native -syntax to be safe (findings §9 Q2)? Without this, non-Markdown shards degrade to -read-only (UC-03) — a graceful-degradation floor, not the goal. **Trilium** is the -HTML-native case: text notes are HTML (CKEditor5), so participation needs HTML↔Markdown -translation — more tractable than Notion's blocks but still lossy for some constructs -(`research/260614-trilium-deep-dive/findings.md` §4, links UC-59). **Wiki.js** is -multi-format (**Markdown primary**, plus HTML and AsciiDoc) with pluggable editors — mostly -native, light translation for the non-MD pages (`research/260614-wikijs-deep-dive/findings.md` -§1). -**Priority:** Later +--- ### UC-43 — Tolerate a shard's storage-backend swap without losing identity @@ -474,91 +489,7 @@ substrate from Markdown-files to a SQLite "DB graph" under a stable graph identi files". **Priority:** Later -### UC-44 — Compose a page by reference (xanadoc / EDL manifest) - -**Actor:** Author -**Goal:** Author a page whose canonical body is an ordered list of spans pulled by -reference from one or more shards, stored as a composition manifest rather than a copy. -**Source:** xanadu, intent -**Notes:** Xanadu EDL/xanadoc — a document that contains no content, only span -references plus link tables, assembled by the client -(`research/260614-xanadu-deep-dive/findings.md` §2). The reference-not-copy embodiment -of INTENT "lazy projection over eager copying" and "union without erasure". Stronger -than UC-32 (single inline span): the *whole page* is a manifest. Requires the wiki page -model to admit a reference-list canonical form — flag for page-model spec. Open: -core vs. adapter vs. reference-UI; MVP vs. deferred with UC-32 (findings §11 Q2). -**Priority:** Later - -### UC-45 — Reverse transclusion: find all appearances of a span - -**Actor:** Reader or maintainer -**Goal:** Given a span (paragraph/section/page), find every page and shard where that -content appears or is transcluded. -**Source:** xanadu, intent -**Notes:** Xanadu content "remembers its identity and traces back to all its -appearances" (`research/260614-xanadu-deep-dive/findings.md` §4). Union BackLinks -generalized from page links to sub-page content identity. Depends on a content-identity -mechanism (UC-46) and on span addressing as an adapter capability (`SHARD-WP-0002`). -Open: exact-identity only vs. fuzzy/derived tracking (findings §11 Q4). -**Priority:** Later - -### UC-46 — Detect content-identity equivalence across shards - -**Actor:** Reader or orchestrator -**Goal:** Determine that two pages in different shards are the same or derived content -by content/span overlap, without relying on matching titles or paths. -**Source:** xanadu, intent -**Notes:** Xanadu compares documents by **span-set intersection** over an invariant -content pool (`research/260614-xanadu-deep-dive/findings.md` §5). Supplies the -equivalent-page identity model left open in UC-27 with a *path-independent* detection -mechanism — equivalence is detected, not enforced (parallel versions stay visible per -UC-27, not collapsed). Adapter advertises its content fingerprint (Git blob hash, -normalized-text hash, none). Open: core vs. adapter-index; cost at wiki scale without -enfilades (findings §11 Q3). -**Priority:** Later - -### UC-47 — Navigate the information space along a chosen relationship dimension - -**Actor:** Reader -**Goal:** Traverse pages along a *selected* relationship axis — namespace, created-from -genealogy, version history, owning shard, equivalence, or recent-change order — rather -than a single fixed hierarchy. -**Source:** zigzag, intent -**Notes:** ZigZag/zzstructure treats each relationship as a first-class **dimension**; -a page is a cell at the intersection of many independent ranks -(`research/260614-zigzag-deep-dive/findings.md` §2, §5). Reframes the existing derived -views (UC-05, UC-17–UC-20) as *dimensions + rasters* under one vocabulary. Embodies -union-without-erasure: every relationship co-equal, none privileged. Open: public -navigation API vs. internal model (findings §10 Q1). **AFFiNE** ships the commercial -proof: docs, whiteboards, and databases are *views of the same block set* -(`research/260614-localfirst-workspaces-deep-dive/findings.md` §2). -**Priority:** Later - -### UC-48 — Pivot two relationships into a cross-tab view (H-view) - -**Actor:** Reader -**Goal:** Cross-tabulate the union by two dimensions at once — e.g. namespace × shard, -or page × versions-across-shards — and pivot to re-cross by a different pair. -**Source:** zigzag -**Notes:** ZigZag **H-view** shows two dimensions through a cursor, one horizontal one -vertical, with only existing cells present (`research/260614-zigzag-deep-dive/findings.md` -§3). A differentiated exploration primitive for federation/provenance. Open: reference-UI -investment vs. research-only (findings §10 Q4). **AFFiNE**'s page/edgeless/DB modes over -one block set are this idea shipped (`research/260614-localfirst-workspaces-deep-dive/findings.md` -§2). -**Priority:** Later - -### UC-49 — Navigate created-from / fork genealogy as a first-class dimension - -**Actor:** Reader or maintainer -**Goal:** Follow a page's derivation lineage — what it was forked/remixed/imported -from, and what was derived from it — as a navigable rank. -**Source:** zigzag, federation, intent -**Notes:** Genealogy is a *functional* relation (one origin) that fits a zzstructure -dimension natively (`research/260614-zigzag-deep-dive/findings.md` §4, §5). Requires a -genealogy edge recorded at fork/remix/import time (UC-26, UC-29) in the coordination -journal. Makes provenance a traversal, not a buried footer (complements UC-24). -**Priority:** Later +--- ### UC-50 — Attach a block-graph database wiki as a shard, mapping blocks to the page model @@ -582,58 +513,7 @@ of the block-tool family — block-graph semantics over plain Markdown files, no UC-62 (`research/260614-logseq-deep-dive/findings.md` §1–§2). **Priority:** Later -### UC-51 — Adopt a shard's native span IDs as portable span addresses - -**Actor:** Orchestrator / adapter -**Goal:** Where a backend mints stable sub-page identifiers (Roam `:block/uid`), adopt -them as the span address for transclusion, overlay, and reverse-lookup, rather than -inventing one. -**Source:** roam, xanadu, intent -**Notes:** Roam ships the fine-grained stable address that Xanadu's tumblers -(`research/260614-xanadu-deep-dive/findings.md` §3) and the catalog left open — a short -opaque per-block UID, public and referenceable (`research/260614-roam-deep-dive/findings.md` -§2, §7). Enables UC-44/45 at sub-page granularity; falls back to content-fingerprint -(UC-46) or path+range where no native ID exists. Open: use native ID directly or wrap in -a shard-scoped address to avoid cross-shard collision and survive projection (findings -§11 Q1). Obsidian shows the **text-embedded** variant: `^block-id` and heading anchors -live in the Markdown text — git-diffable and portable (survives a file copy) but opt-in -(`research/260614-obsidian-deep-dive/findings.md` §2), vs Roam's mandatory DB-minted -UID. Notion is a second store-minted case: per-block **UUID v4**, exposed via the REST -API (`research/260614-notion-deep-dive/findings.md` §1). **Joplin** marks the spectrum's -middle: a store-minted **page-level** 32-char ID with `:/` links that survive -rename/move (`research/260614-joplin-deep-dive/findings.md` §1) — coarser than a block -UUID, more stable than a path. **Logseq** is the **sweet spot**: a block-level `id:: uuid` -stored **in the Markdown text** — fine-grained *and* git-diffable/portable at once, -resolving the Roam(DB-minted) vs Obsidian(page-level) tension -(`research/260614-logseq-deep-dive/findings.md` §2). **CRDT** shards -(Anytype/AFFiNE/AppFlowy) mint object/block IDs as part of the CRDT structure — fine- -grained, store-assigned (`research/260614-localfirst-workspaces-deep-dive/findings.md` -§6). -**Priority:** Later - -### UC-52 — Delegate derived views to a shard's native query engine - -**Actor:** Orchestrator -**Goal:** When a shard exposes a native query engine, compute derived views (backlinks, -recent changes, typed queries) by delegating to it instead of scanning the projection. -**Source:** roam, intent -**Notes:** In Roam, derived views *are* Datalog queries over the datom graph -(`research/260614-roam-deep-dive/findings.md` §4). Makes "native query" an adapter -capability the orchestrator can key off (vs. computing views itself over the -projection). Operationalizes the ZigZag "dimensions + rasters" insight -(`research/260614-zigzag-deep-dive/findings.md` §5) and relates to UC-05/UC-34. Obsidian -nuance: query can be an *ecosystem plugin* (Dataview), **not core** — so "native query" -is adapter/plugin-provided and must not be assumed -(`research/260614-obsidian-deep-dive/findings.md` §7). **Notion** ships a native -database **query API** (filters/sorts) — a strong delegation target -(`research/260614-notion-deep-dive/findings.md` §2, §4). **Logseq** shows the third path: -Datalog over a **derived** index built from plain files — neither native-DB nor plugin; -when no engine exists, shard-wiki can build the index itself (UC-63, -`research/260614-logseq-deep-dive/findings.md` §3). **Wikibase** is the far end: -**SPARQL** over an RDF projection with **federated `SERVICE`** cross-endpoint joins -(`research/260614-wikibase-deep-dive/findings.md` §2) — a graph-query tier above -datalog/filters, and `SERVICE` is itself a query-time federation primitive (UC-74). -**Priority:** Later +--- ### UC-53 — Attach a local-first Markdown vault with a live concurrent native editor @@ -651,56 +531,7 @@ live `vault` events (UC-38, findings §4). Needs **external-writer tolerance** conflicts. Exclude `.obsidian/` as shard-local config, not page content. **Priority:** Later -### UC-54 — Define a page as a live query over the union - -**Actor:** Author -**Goal:** Author a page whose body is materialized from a saved query over the union -(e.g. "all open tasks", "all pages tagged X"), refreshed as the union changes. -**Source:** obsidian, roam, intent -**Notes:** The Obsidian **Dataview** (4.4M downloads) / **Tasks** (3.6M) pattern, and -Roam `{{query}}` — query-defined dynamic pages -(`research/260614-obsidian-deep-dive/findings.md` §7). Distinct from UC-44 (reference/ -span manifest) and UC-52 (delegating *computation* of an existing view): here the *page -itself* is a query. Open: core page type vs. adapter vs. reference-UI/plugin (findings -§11 Q2). May delegate execution to a shard's native query engine (UC-52). **Notion** -linked/filtered databases are the commercial instance — one row-set surfaced through many -filtered views (`research/260614-notion-deep-dive/findings.md` §2). -**Priority:** Later - -### UC-55 — Carry non-Markdown content types as typed or opaque assets - -**Actor:** Maintainer or author -**Goal:** Attach and present a shard's non-Markdown content — drawings (Excalidraw), -spatial canvases (JSON Canvas), images, attachments — as typed or opaque assets with -provenance, without flattening them into Markdown or dropping them. -**Source:** obsidian, intent -**Notes:** The **#1 Obsidian plugin is Excalidraw (6.4M)** — users keep non-Markdown -content in "Markdown" vaults (`research/260614-obsidian-deep-dive/findings.md` §7). -Extends UC-34's no-lossy-flatten rule from structured-text to binary/spatial content. -Pushes the **wiki page model**: page vs. typed asset vs. opaque blob — a page-model -decision, not just adapter config (findings §10). JSON Canvas is an open format worth -first-class support. **Joplin** resources (attachments, each with an ID, linked `:/`) -are the same demand in a sync-mirror shard (`research/260614-joplin-deep-dive/findings.md` -§5). **Logseq whiteboards** (tldraw JSON) are the same in a file-store block shard -(`research/260614-logseq-deep-dive/findings.md` §6). **AFFiNE** edgeless canvas, **AppFlowy** -boards/calendars, and **Anytype** objects/files are the same demand in CRDT shards -(`research/260614-localfirst-workspaces-deep-dive/findings.md` §5). -**Priority:** Later - -### UC-56 — Publish a curated projection to an external read-only target - -**Actor:** Maintainer -**Goal:** Publish a selected projection of the union (or a shard) to an external -read-only target — a static site or hosted page set — preserving provenance. -**Source:** obsidian, intent -**Notes:** The Obsidian Publish / **Quartz** / Digital Garden pattern — outbound -publish (`research/260614-obsidian-deep-dive/findings.md` §7, §10). Formalizes the -`publish` capability from INTENT's adapter-capability list; **complements UC-37** -(inbound static-export *attach*) as its outbound mirror. Open: core vs. publish-adapter -family; interaction with overlays and projection freshness (findings §11 Q4). **Notion** -adds the closed-SaaS instance: **publish-to-web** renders pages as read-only public -pages (`research/260614-notion-deep-dive/findings.md` §4). -**Priority:** Later +--- ### UC-57 — Attach a closed hosted shard via its external API only @@ -731,41 +562,7 @@ external-API mode carries a **payload-format facet** (block-JSON / GraphQL / HTM adapter profile. **Priority:** Later -### UC-58 — Attach a typed database with schema, relations, and views - -**Actor:** Maintainer -**Goal:** Attach a structured database (Notion-style) as a shard — preserving its -schema (typed properties), its inter-record **relations** and **rollups/formulas**, and -its multiple **views** — without flattening the schema or the relations into prose. -**Source:** notion, intent -**Notes:** The apex of UC-34/UC-39: not annotations on prose, nor one form per page, but -a **collection with a schema** whose rows are pages joined by **typed, bidirectional -relations**, shown through many views (table/board/calendar/gallery) -(`research/260614-notion-deep-dive/findings.md` §2). Presses the page model: collection + -schema + relations, not just a page (findings §9). Relations map to the union link graph -and/or a relation index (cf. ZigZag many-to-many, UC-47/48); views relate to UC-54. -Deferred to `SHARD-WP-0002`. **Local-first** variants exist: **Anytype**'s user-editable -typed object graph (types + relations = an ontology) and **AppFlowy**'s Notion-style DBs, -both CRDT-backed (`research/260614-localfirst-workspaces-deep-dive/findings.md` §1, §3) — -the typed-collection demand is not exclusive to hosted SaaS. -**Priority:** Later - -### UC-59 — Translate a proprietary content model with an explicit fidelity report - -**Actor:** Orchestrator / adapter -**Goal:** Project and edit a shard whose content model does not round-trip to Markdown -(Notion blocks/rich-text, databases, relations) by translating **lossily but -transparently** — surfacing what degraded or did not map, rather than silently dropping -it. -**Source:** notion, intent -**Notes:** Notion is the heaviest translation case — proprietary block + rich-text model, -and its own Markdown/CSV export is lossy (`research/260614-notion-deep-dive/findings.md` -§3). **Distinct from UC-42** (Foswiki TML↔HTML *lossless* round-trip): here translation -is fundamentally lossy, so **fidelity becomes data** — a per-shard/per-page report of -what projects cleanly vs. degrades, with non-mappable elements preserved as -provenance/sidecar. Embodies union-without-erasure by making *loss of fidelity* visible. -Open: report format and where it surfaces (findings §10 Q3). -**Priority:** Later +--- ### UC-60 — Attach a tool's documented sync / interchange representation @@ -786,6 +583,8 @@ INTENT's WebDAV/Nextcloud/S3 participants. Needs a **format profile** in the ada (findings §8). **Priority:** Later +--- + ### UC-61 — Attach an encrypted-at-rest shard with content opacity **Actor:** Maintainer @@ -808,6 +607,8 @@ notes coexist with plaintext notes in one shard, so opacity is per-note, not who (`research/260614-trilium-deep-dive/findings.md` §6). **Priority:** Later +--- + ### UC-62 — Attach a block-graph-on-plain-files shard **Actor:** Maintainer @@ -826,21 +627,7 @@ format profile** (parse `id::`/`((uuid))`/`key::`/outline) or via the in-app plu (UC-43). **Priority:** Later -### UC-63 — Serve structured queries over a file-backed shard via a derived index - -**Actor:** Reader or orchestrator -**Goal:** Run structured queries (tasks, tagged blocks, typed properties) over a -file-backed shard that exposes no native query engine, using an index the orchestrator or -adapter builds and rebuilds from the files. -**Source:** logseq, intent -**Notes:** Logseq proves a **file-backed** store supports rich **Datalog** queries via a -**derived DataScript index** (files canonical, graph derived — -`research/260614-logseq-deep-dive/findings.md` §1, §3). The converse of UC-52 (delegate to -a *native* engine): here shard-wiki **builds** the index over the projection when none -exists. Operationalizes the ZigZag dimensions / Roam-Notion query model on a file shard. -Open: built by adapter (per-shard) or core (over the union); persisted vs rebuilt -(findings §10 Q2). Belongs to the T16 navigation layer + T11 capabilities. -**Priority:** Later +--- ### UC-64 — Attach a CRDT-synced local-first shard with native merge @@ -861,6 +648,8 @@ self-host sync endpoint (UC-57). Like Joplin, do **not** re-drive the backend's ops vs out-of-band patches (findings §10 Q1–Q2). **Priority:** Later +--- + ### UC-65 — Attach a peer-to-peer / decentralized shard with no single endpoint **Actor:** Maintainer @@ -877,6 +666,8 @@ file-store / in-engine-host / external-API (UC-40/38/57). Combines with **conten whether shard-wiki holds keys (findings §10 Q3–Q4). Ties [[shard-wiki-auth-in-core-decision]]. **Priority:** Later +--- + ### UC-66 — Attach a shard with a DAG hierarchy (note cloning) **Actor:** Maintainer @@ -895,21 +686,7 @@ cf. Xanadu/ZigZag clone, UC-44/45). Open: model as one page with N placements vs transclusion into N locations (findings §11 Q1). **Priority:** Later -### UC-67 — Preserve inherited and templated attributes (effective vs own metadata) - -**Actor:** Reader or maintainer -**Goal:** Project a structured shard whose metadata is **computed** — a page's effective -attributes derive from its own values plus inherited (ancestor) and templated values — -distinguishing **effective vs own** with per-attribute provenance, not flattening. -**Source:** trilium, intent -**Notes:** Trilium attributes (labels `#tag`, typed relations `~relation`) can be -**inherited down the subtree** and injected by **templates** (`~template`), so effective -metadata = own + inherited + templated (`research/260614-trilium-deep-dive/findings.md` -§3). Extends UC-34/UC-58 with a new wrinkle: **metadata is computed, not just stored** — -record each attribute's provenance (own / inherited-from / template). Open: materialize -effective values (snapshot) vs compute live from the shard's tree/templates (findings §11 -Q2). Templates also reinforce UC-15 (blueprints). -**Priority:** Later +--- ### UC-68 — Attach an engine-maintained bidirectional Git mirror of clean Markdown @@ -935,6 +712,8 @@ to race and **write-by-commit is safe** *engine-maintained mirrors* (DB canonical), not to git-canonical stores. **Priority:** Later +--- + ### UC-69 — Attach via a typed, introspectable API (schema discovery + selective projection) **Actor:** Orchestrator / adapter @@ -968,85 +747,7 @@ shard is naturally a read/project + overlay target, never silent remote mutation SHARD-WP-0002 T14 (attachment mode), T11 (capability profile). **Priority:** Later -### UC-71 — Coordination journal as an append-only semantic-action log with provenance - -**Actor:** Core orchestrator -**Goal:** Model the coordination journal as a **per-page append-only log of semantic -actions** (`create`/`add`/`edit`/`move`/`remove`/`fork`) carrying **provenance entries** -(fork records the source site), with the page state **derived by replaying** the log and -divergence **located by comparing** logs. -**Source:** federation, intent -**Notes:** Directly adopts the fedwiki **journal** shape — the story is a materialized -view of the journal, fork entries serialize a **provenance DAG**, and per-entry sequence -numbers make the fork cut-point identifiable -(`research/260614-federated-wiki-deep-dive/findings.md` §2, §6). This is concrete prior art -for INTENT's coordination journal: a **third merge model** beside git 3-way and CRDT -auto-merge — a coarse semantic op-log applied manually via fork. Feeds SHARD-WP-0002 T13 -(history portability / merge model) and T1–T5 (federation). -**Priority:** Later - -### UC-72 — Federate by fork-with-provenance across a neighborhood / chorus - -**Actor:** Reader / curator -**Goal:** Assemble a **union from sovereign peer shards** discovered by **link and fork** -(a *neighborhood*) or by an explicit **roster**, **search across that set**, and preserve a -**chorus of co-equal, provenance-linked versions** without forcing a canonical — pulling -another's changes by forking them. -**Source:** federation, intent -**Notes:** Fedwiki's neighborhood (dynamic, link/fork-discovered) vs roster (curated) -membership and "chorus of voices" no-canonical stance -(`research/260614-federated-wiki-deep-dive/findings.md` §3, §4) model -**union-without-erasure** at the coordination layer: divergence is normal and visible, -reconciliation is an explicit human/policy step (mechanism over policy). Open: does a -chorus compose with shards that assert a canonical? Feeds SHARD-WP-0002 T1–T5; relates -UC-05/UC-27 (union/chorus), UC-26 (fork). -**Priority:** Later - -### UC-73 — Attach a typed entity-statement (RDF) knowledge-graph shard - -**Actor:** Orchestrator / adapter -**Goal:** Attach a **Wikibase** instance as a **typed entity-statement shard** — items and -properties, statements = claim + qualifiers + references + rank — and project entities to a -rendered page view (lossy to Markdown) **without flattening away the graph**. -**Source:** wikiengines, intent -**Notes:** The **structure far-end** beyond Notion DB / XWiki XObjects / Trilium relations: -a true typed knowledge graph with `somevalue`/`novalue` known-unknowns -(`research/260614-wikibase-deep-dive/findings.md` §1). Content **is not Markdown** — render -is a lossy projection (UC-55), so attach as a structured shard and either keep the graph as -the canonical payload (T12) or offer a rendered view, never a silent flatten. Feeds -SHARD-WP-0002 T12 (typed-graph page payload), T16 (stable opaque identity). -**Priority:** Later - -### UC-74 — Graph-query the union (SPARQL) and federate queries across endpoints - -**Actor:** Reader / analyst -**Goal:** Query graph-capable shards with a **graph query language (SPARQL)** and **federate -queries across endpoints** (`SERVICE`) — a query-time cross-shard join distinct from -structural (fork/neighborhood) federation. -**Source:** wikiengines, intent -**Notes:** SPARQL over the RDF projection (Wikidata Query Service / Blazegraph) is the -**native-query far-end** above Roam/Logseq datalog and Notion filters (UC-52); `SERVICE` is -a **query-time federation** primitive beside fedwiki's structural federation (UC-72) -(`research/260614-wikibase-deep-dive/findings.md` §2). Open: union-level common query vs -pass-through to graph-capable shards. Feeds SHARD-WP-0002 native-query tiering; relates -UC-63 (derived index — WDQS is one). -**Priority:** Later - -### UC-75 — Preserve statement-level provenance (references + rank) - -**Actor:** Core orchestrator -**Goal:** Preserve **provenance at the assertion level** — references and **rank** attached -to each *statement*, not just per page or per shard — so contradictory values can coexist -with a curation signal. -**Source:** wikiengines, intent -**Notes:** Wikibase attaches **references** (sources) and a **rank** -(`preferred`/`normal`/`deprecated`) to each statement -(`research/260614-wikibase-deep-dive/findings.md` §1, §5) — provenance granularity **finer** -than shard-wiki's per-page model, and the *structured* analogue of fedwiki's chorus (UC-72) -and "view multiple versions" (UC-27). The page model + coordination journal should **allow** -sub-page/per-assertion provenance even if MVP records per page. Enriches UC-24; feeds -SHARD-WP-0002 T12 + provenance model. -**Priority:** Later +--- ### UC-76 — Attach a git-forge wiki by cloning its dedicated wiki repo @@ -1063,6 +764,8 @@ is safe (resolves catalog open-Q22). The **universal** attach path across all th INTENT names Gitea wikis explicitly. Feeds SHARD-WP-0002 T14 (file-store attach), T11. **Priority:** MVP +--- + ### UC-77 — Attach/write a forge wiki via the forge's wiki API (capability varies) **Actor:** Orchestrator / adapter @@ -1078,6 +781,8 @@ external-API host sub-mode (UC-38) beside the file-store attach (UC-76). Feeds SHARD-WP-0002 T11 (capability flag), T14 (binding). **Priority:** Later +--- + ### UC-78 — Attach a single-file self-contained wiki (whole-file write granularity) **Actor:** Orchestrator / adapter @@ -1096,6 +801,8 @@ ignore the embedded engine). Feeds SHARD-WP-0002 T11 (whole-file tier), T14 (sin `.tid` binding; cf. UC-43/UC-62). **Priority:** Later +--- + ### UC-79 — Attach a git-backed compile-to-static wiki (source is the shard) **Actor:** Orchestrator / adapter @@ -1113,23 +820,7 @@ the git+Markdown adapter with forge wikis (UC-76). Feeds SHARD-WP-0002 T4 (feder (publish/projection). **Priority:** Later -### UC-80 — Attach a SaaS live-doc shard with embedded structured objects - -**Actor:** Orchestrator / adapter -**Goal:** Attach a **SaaS live-document shard** (Salesforce Quip) whose pages **mix prose -with embedded live structured objects** (spreadsheets, live apps) via a **REST API with -lossy HTML import/export**, under **enterprise (Salesforce) identity**. -**Source:** wikiengines, intent -**Notes:** Quip is a closed-SaaS document+spreadsheet hybrid — a page is prose interleaved -with **inline spreadsheets/live apps**, reachable only by REST, content crossing as **HTML** -(lossy to Markdown; embedded objects degrade) (`research/260614-quip-deep-dive/findings.md` -§1, §2). Generalizes the external-API mode (UC-57) with an **HTML payload** variant beside -Notion block-JSON and Wiki.js GraphQL, and adds **inline embedded structured objects** to -the page model (UC-55/UC-58) — surface them with provenance, never silent-flatten (UC-59). -Honor **Salesforce ACL** (UC-06); default to read/projection/overlay given rate limits + -lossy export. Feeds SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (inline -objects), T14. -**Priority:** Later +--- ### UC-81 — Attach a DB-backed wiki with no file store/API by reading its store directly @@ -1149,6 +840,8 @@ risks app invariants → default read/projection/overlay. Feeds SHARD-WP-0002 T1 binding), T13. **Priority:** Later +--- + ### UC-82 — Attach a minimal flat-file wiki as the graceful-degradation baseline **Actor:** Maintainer / adapter @@ -1166,9 +859,435 @@ and must report history as **partial** when `keep/` is truncated (provenance hon Feeds SHARD-WP-0002 T11 (minimal/floor capability profile), T13 (partial-history import). **Priority:** Later +## C. Page model, structure & content fidelity + +*What a page can hold (typed records, knowledge graphs, embedded / non-Markdown content) and how fidelity is preserved on translation.* + +### UC-34 — Attach a structured or semantic shard without lossy flattening + +**Actor:** Maintainer +**Goal:** Attach an engine whose pages carry structured or queryable data beyond +Markdown (Semantic MediaWiki annotations, XWiki objects/forms) and project it +without silently discarding the structure. +**Source:** wikiengines, intent +**Notes:** Engine scan shows "wiki page" spans flat Markdown to queryable +knowledge objects. Markdown-first must **degrade gracefully**, not flatten: +needs a passthrough / sidecar-metadata / provenance escape hatch. Page-model +question deferred to `SHARD-WP-0002` (findings §6 Q1). Distinct from UC-02 +(assumes Markdown-shaped pages). XWiki is the concrete exemplar: pages carry typed +XObjects against an XClass schema (`research/260613-xwiki-deep-dive/findings.md` +§2.3); UC-39 covers the extreme where the page is *only* structure. TWiki shows the +**git-friendly** variant: TWiki Forms store fields as `%META:FIELD%` *inside the +topic text file*, so structure is diffable rather than locked in a DB +(`research/260613-twiki-deep-dive/findings.md` §2.3). Roam is the modern exemplar: +`key:: value` attributes over a datom graph, queryable via Datalog +(`research/260614-roam-deep-dive/findings.md` §3, §4) — structure to preserve via +sidecar metadata, and a candidate for query delegation (UC-52). Obsidian shows the +**git-diffable in-file** variant: YAML frontmatter/properties live in the Markdown text +and are queried by the Dataview plugin (`research/260614-obsidian-deep-dive/findings.md` +§3) — structure as portable text, not DB state. **Notion** is the apex of the DB-locked +end: typed database properties with relations/rollups/formulas, lossy to Markdown — +see UC-58 (`research/260614-notion-deep-dive/findings.md` §2). **Logseq** sits between: +`key:: value` block/page properties live in the Markdown text (git-diffable) yet are +queried via a derived Datalog graph (`research/260614-logseq-deep-dive/findings.md` §2–§3) +— in-text structure at block granularity. **Trilium** adds **computed** structure: labels ++ typed relations that are **inherited + templated**, so effective metadata ≠ stored +metadata — see UC-67 (`research/260614-trilium-deep-dive/findings.md` §3). +**Priority:** Later + --- -## B. Knowledge work and collaboration +### UC-39 — Attach a wiki-as-application-platform shard (pages as typed records) + +**Actor:** Maintainer +**Goal:** Attach an engine where pages are structured records or forms with little +or no prose body (XWiki AppWithinMinutes apps / XObjects), and represent them in the +union without inventing a fake Markdown body. +**Source:** wikiengines, intent +**Notes:** The extreme of UC-34 — not *annotations on prose* but **bodiless +structured pages**. Forces the question: does the page model require a Markdown body, +or can a page be purely typed data (`research/260613-xwiki-deep-dive/findings.md` +§8 Q2)? Affects union views, diff, and search. Deferred to `SHARD-WP-0002`. +Foswiki shows a middle point: MetaDataPlugin stores **multiple** structured records +per topic, still as `%META%` in text (`research/260613-foswiki-deep-dive/findings.md` +§4) — the page model must allow N typed records, not one form. **Notion** pushes +further: a *database* is a collection with a schema whose rows are pages joined by typed +relations — see UC-58 (`research/260614-notion-deep-dive/findings.md` §2). +**Priority:** Later + +--- + +### UC-42 — Read and write a non-Markdown shard via lossless syntax translation + +**Actor:** Author or maintainer +**Goal:** Attach a shard whose native markup is not Markdown (TWiki/Foswiki TML, +XWiki syntax) and read it into the Markdown-first model — and write Markdown overlays +back — through **bidirectional, lossless syntax translation**, instead of treating it +as read-only. +**Source:** wikiengines, intent +**Notes:** Realizes *Markdown-first, backend-neutral* for **prose** (UC-34/39 cover +*structure*). Feasibility proven by Foswiki's **WysiwygPlugin** (TML→HTML for editing, +HTML→TML losslessly on save) (`research/260613-foswiki-deep-dive/findings.md` §5). +Open: is round-trip lossless enough, or must overlays be stored in the shard's native +syntax to be safe (findings §9 Q2)? Without this, non-Markdown shards degrade to +read-only (UC-03) — a graceful-degradation floor, not the goal. **Trilium** is the +HTML-native case: text notes are HTML (CKEditor5), so participation needs HTML↔Markdown +translation — more tractable than Notion's blocks but still lossy for some constructs +(`research/260614-trilium-deep-dive/findings.md` §4, links UC-59). **Wiki.js** is +multi-format (**Markdown primary**, plus HTML and AsciiDoc) with pluggable editors — mostly +native, light translation for the non-MD pages (`research/260614-wikijs-deep-dive/findings.md` +§1). +**Priority:** Later + +--- + +### UC-55 — Carry non-Markdown content types as typed or opaque assets + +**Actor:** Maintainer or author +**Goal:** Attach and present a shard's non-Markdown content — drawings (Excalidraw), +spatial canvases (JSON Canvas), images, attachments — as typed or opaque assets with +provenance, without flattening them into Markdown or dropping them. +**Source:** obsidian, intent +**Notes:** The **#1 Obsidian plugin is Excalidraw (6.4M)** — users keep non-Markdown +content in "Markdown" vaults (`research/260614-obsidian-deep-dive/findings.md` §7). +Extends UC-34's no-lossy-flatten rule from structured-text to binary/spatial content. +Pushes the **wiki page model**: page vs. typed asset vs. opaque blob — a page-model +decision, not just adapter config (findings §10). JSON Canvas is an open format worth +first-class support. **Joplin** resources (attachments, each with an ID, linked `:/`) +are the same demand in a sync-mirror shard (`research/260614-joplin-deep-dive/findings.md` +§5). **Logseq whiteboards** (tldraw JSON) are the same in a file-store block shard +(`research/260614-logseq-deep-dive/findings.md` §6). **AFFiNE** edgeless canvas, **AppFlowy** +boards/calendars, and **Anytype** objects/files are the same demand in CRDT shards +(`research/260614-localfirst-workspaces-deep-dive/findings.md` §5). +**Priority:** Later + +--- + +### UC-58 — Attach a typed database with schema, relations, and views + +**Actor:** Maintainer +**Goal:** Attach a structured database (Notion-style) as a shard — preserving its +schema (typed properties), its inter-record **relations** and **rollups/formulas**, and +its multiple **views** — without flattening the schema or the relations into prose. +**Source:** notion, intent +**Notes:** The apex of UC-34/UC-39: not annotations on prose, nor one form per page, but +a **collection with a schema** whose rows are pages joined by **typed, bidirectional +relations**, shown through many views (table/board/calendar/gallery) +(`research/260614-notion-deep-dive/findings.md` §2). Presses the page model: collection + +schema + relations, not just a page (findings §9). Relations map to the union link graph +and/or a relation index (cf. ZigZag many-to-many, UC-47/48); views relate to UC-54. +Deferred to `SHARD-WP-0002`. **Local-first** variants exist: **Anytype**'s user-editable +typed object graph (types + relations = an ontology) and **AppFlowy**'s Notion-style DBs, +both CRDT-backed (`research/260614-localfirst-workspaces-deep-dive/findings.md` §1, §3) — +the typed-collection demand is not exclusive to hosted SaaS. +**Priority:** Later + +--- + +### UC-59 — Translate a proprietary content model with an explicit fidelity report + +**Actor:** Orchestrator / adapter +**Goal:** Project and edit a shard whose content model does not round-trip to Markdown +(Notion blocks/rich-text, databases, relations) by translating **lossily but +transparently** — surfacing what degraded or did not map, rather than silently dropping +it. +**Source:** notion, intent +**Notes:** Notion is the heaviest translation case — proprietary block + rich-text model, +and its own Markdown/CSV export is lossy (`research/260614-notion-deep-dive/findings.md` +§3). **Distinct from UC-42** (Foswiki TML↔HTML *lossless* round-trip): here translation +is fundamentally lossy, so **fidelity becomes data** — a per-shard/per-page report of +what projects cleanly vs. degrades, with non-mappable elements preserved as +provenance/sidecar. Embodies union-without-erasure by making *loss of fidelity* visible. +Open: report format and where it surfaces (findings §10 Q3). +**Priority:** Later + +--- + +### UC-67 — Preserve inherited and templated attributes (effective vs own metadata) + +**Actor:** Reader or maintainer +**Goal:** Project a structured shard whose metadata is **computed** — a page's effective +attributes derive from its own values plus inherited (ancestor) and templated values — +distinguishing **effective vs own** with per-attribute provenance, not flattening. +**Source:** trilium, intent +**Notes:** Trilium attributes (labels `#tag`, typed relations `~relation`) can be +**inherited down the subtree** and injected by **templates** (`~template`), so effective +metadata = own + inherited + templated (`research/260614-trilium-deep-dive/findings.md` +§3). Extends UC-34/UC-58 with a new wrinkle: **metadata is computed, not just stored** — +record each attribute's provenance (own / inherited-from / template). Open: materialize +effective values (snapshot) vs compute live from the shard's tree/templates (findings §11 +Q2). Templates also reinforce UC-15 (blueprints). +**Priority:** Later + +--- + +### UC-73 — Attach a typed entity-statement (RDF) knowledge-graph shard + +**Actor:** Orchestrator / adapter +**Goal:** Attach a **Wikibase** instance as a **typed entity-statement shard** — items and +properties, statements = claim + qualifiers + references + rank — and project entities to a +rendered page view (lossy to Markdown) **without flattening away the graph**. +**Source:** wikiengines, intent +**Notes:** The **structure far-end** beyond Notion DB / XWiki XObjects / Trilium relations: +a true typed knowledge graph with `somevalue`/`novalue` known-unknowns +(`research/260614-wikibase-deep-dive/findings.md` §1). Content **is not Markdown** — render +is a lossy projection (UC-55), so attach as a structured shard and either keep the graph as +the canonical payload (T12) or offer a rendered view, never a silent flatten. Feeds +SHARD-WP-0002 T12 (typed-graph page payload), T16 (stable opaque identity). +**Priority:** Later + +--- + +### UC-80 — Attach a SaaS live-doc shard with embedded structured objects + +**Actor:** Orchestrator / adapter +**Goal:** Attach a **SaaS live-document shard** (Salesforce Quip) whose pages **mix prose +with embedded live structured objects** (spreadsheets, live apps) via a **REST API with +lossy HTML import/export**, under **enterprise (Salesforce) identity**. +**Source:** wikiengines, intent +**Notes:** Quip is a closed-SaaS document+spreadsheet hybrid — a page is prose interleaved +with **inline spreadsheets/live apps**, reachable only by REST, content crossing as **HTML** +(lossy to Markdown; embedded objects degrade) (`research/260614-quip-deep-dive/findings.md` +§1, §2). Generalizes the external-API mode (UC-57) with an **HTML payload** variant beside +Notion block-JSON and Wiki.js GraphQL, and adds **inline embedded structured objects** to +the page model (UC-55/UC-58) — surface them with provenance, never silent-flatten (UC-59). +Honor **Salesforce ACL** (UC-06); default to read/projection/overlay given rate limits + +lossy export. Feeds SHARD-WP-0002 T11 (payload-format + content-opacity), T12 (inline +objects), T14. +**Priority:** Later + +## D. Addressing, identity & query + +*Span / identity addressing, transclusion-as-reference, dimensional navigation, and query over the union.* + +### UC-32 — Transclude remote span with live freshness + +**Actor:** Author or reader +**Goal:** Embed a portion of a remote page inline with visible origin and +refreshable content. +**Source:** federation, intent +**Notes:** Xanadu transclusion pattern; stronger than UC-03 whole-page +projection. Provenance and staleness must be explicit. Xanadu deep dive sharpens this: +transclusion should be **content-identity based and bidirectional** (content is "knowably +in more than one place" and aware of its appearances), not a one-way path fetch — +enables UC-45 reverse lookup (`research/260614-xanadu-deep-dive/findings.md` §4). See +UC-44 for the whole-page composition-manifest form. **Roam ships this**: block embeds +transclude by `:block/uid` live (not copied), proving transclusion is a cheap data-layer +capability over an addressable store (`research/260614-roam-deep-dive/findings.md` §3, +§7) — argues for transclusion in core over the union, surfaced by UI. Depends on span +addressing (UC-51). **Logseq** does the same on *files*: `{{embed ((uuid))}}` transcludes +by an in-file block ID (`research/260614-logseq-deep-dive/findings.md` §2). +**Priority:** Later + +--- + +### UC-44 — Compose a page by reference (xanadoc / EDL manifest) + +**Actor:** Author +**Goal:** Author a page whose canonical body is an ordered list of spans pulled by +reference from one or more shards, stored as a composition manifest rather than a copy. +**Source:** xanadu, intent +**Notes:** Xanadu EDL/xanadoc — a document that contains no content, only span +references plus link tables, assembled by the client +(`research/260614-xanadu-deep-dive/findings.md` §2). The reference-not-copy embodiment +of INTENT "lazy projection over eager copying" and "union without erasure". Stronger +than UC-32 (single inline span): the *whole page* is a manifest. Requires the wiki page +model to admit a reference-list canonical form — flag for page-model spec. Open: +core vs. adapter vs. reference-UI; MVP vs. deferred with UC-32 (findings §11 Q2). +**Priority:** Later + +--- + +### UC-45 — Reverse transclusion: find all appearances of a span + +**Actor:** Reader or maintainer +**Goal:** Given a span (paragraph/section/page), find every page and shard where that +content appears or is transcluded. +**Source:** xanadu, intent +**Notes:** Xanadu content "remembers its identity and traces back to all its +appearances" (`research/260614-xanadu-deep-dive/findings.md` §4). Union BackLinks +generalized from page links to sub-page content identity. Depends on a content-identity +mechanism (UC-46) and on span addressing as an adapter capability (`SHARD-WP-0002`). +Open: exact-identity only vs. fuzzy/derived tracking (findings §11 Q4). +**Priority:** Later + +--- + +### UC-46 — Detect content-identity equivalence across shards + +**Actor:** Reader or orchestrator +**Goal:** Determine that two pages in different shards are the same or derived content +by content/span overlap, without relying on matching titles or paths. +**Source:** xanadu, intent +**Notes:** Xanadu compares documents by **span-set intersection** over an invariant +content pool (`research/260614-xanadu-deep-dive/findings.md` §5). Supplies the +equivalent-page identity model left open in UC-27 with a *path-independent* detection +mechanism — equivalence is detected, not enforced (parallel versions stay visible per +UC-27, not collapsed). Adapter advertises its content fingerprint (Git blob hash, +normalized-text hash, none). Open: core vs. adapter-index; cost at wiki scale without +enfilades (findings §11 Q3). +**Priority:** Later + +--- + +### UC-47 — Navigate the information space along a chosen relationship dimension + +**Actor:** Reader +**Goal:** Traverse pages along a *selected* relationship axis — namespace, created-from +genealogy, version history, owning shard, equivalence, or recent-change order — rather +than a single fixed hierarchy. +**Source:** zigzag, intent +**Notes:** ZigZag/zzstructure treats each relationship as a first-class **dimension**; +a page is a cell at the intersection of many independent ranks +(`research/260614-zigzag-deep-dive/findings.md` §2, §5). Reframes the existing derived +views (UC-05, UC-17–UC-20) as *dimensions + rasters* under one vocabulary. Embodies +union-without-erasure: every relationship co-equal, none privileged. Open: public +navigation API vs. internal model (findings §10 Q1). **AFFiNE** ships the commercial +proof: docs, whiteboards, and databases are *views of the same block set* +(`research/260614-localfirst-workspaces-deep-dive/findings.md` §2). +**Priority:** Later + +--- + +### UC-48 — Pivot two relationships into a cross-tab view (H-view) + +**Actor:** Reader +**Goal:** Cross-tabulate the union by two dimensions at once — e.g. namespace × shard, +or page × versions-across-shards — and pivot to re-cross by a different pair. +**Source:** zigzag +**Notes:** ZigZag **H-view** shows two dimensions through a cursor, one horizontal one +vertical, with only existing cells present (`research/260614-zigzag-deep-dive/findings.md` +§3). A differentiated exploration primitive for federation/provenance. Open: reference-UI +investment vs. research-only (findings §10 Q4). **AFFiNE**'s page/edgeless/DB modes over +one block set are this idea shipped (`research/260614-localfirst-workspaces-deep-dive/findings.md` +§2). +**Priority:** Later + +--- + +### UC-49 — Navigate created-from / fork genealogy as a first-class dimension + +**Actor:** Reader or maintainer +**Goal:** Follow a page's derivation lineage — what it was forked/remixed/imported +from, and what was derived from it — as a navigable rank. +**Source:** zigzag, federation, intent +**Notes:** Genealogy is a *functional* relation (one origin) that fits a zzstructure +dimension natively (`research/260614-zigzag-deep-dive/findings.md` §4, §5). Requires a +genealogy edge recorded at fork/remix/import time (UC-26, UC-29) in the coordination +journal. Makes provenance a traversal, not a buried footer (complements UC-24). +**Priority:** Later + +--- + +### UC-51 — Adopt a shard's native span IDs as portable span addresses + +**Actor:** Orchestrator / adapter +**Goal:** Where a backend mints stable sub-page identifiers (Roam `:block/uid`), adopt +them as the span address for transclusion, overlay, and reverse-lookup, rather than +inventing one. +**Source:** roam, xanadu, intent +**Notes:** Roam ships the fine-grained stable address that Xanadu's tumblers +(`research/260614-xanadu-deep-dive/findings.md` §3) and the catalog left open — a short +opaque per-block UID, public and referenceable (`research/260614-roam-deep-dive/findings.md` +§2, §7). Enables UC-44/45 at sub-page granularity; falls back to content-fingerprint +(UC-46) or path+range where no native ID exists. Open: use native ID directly or wrap in +a shard-scoped address to avoid cross-shard collision and survive projection (findings +§11 Q1). Obsidian shows the **text-embedded** variant: `^block-id` and heading anchors +live in the Markdown text — git-diffable and portable (survives a file copy) but opt-in +(`research/260614-obsidian-deep-dive/findings.md` §2), vs Roam's mandatory DB-minted +UID. Notion is a second store-minted case: per-block **UUID v4**, exposed via the REST +API (`research/260614-notion-deep-dive/findings.md` §1). **Joplin** marks the spectrum's +middle: a store-minted **page-level** 32-char ID with `:/` links that survive +rename/move (`research/260614-joplin-deep-dive/findings.md` §1) — coarser than a block +UUID, more stable than a path. **Logseq** is the **sweet spot**: a block-level `id:: uuid` +stored **in the Markdown text** — fine-grained *and* git-diffable/portable at once, +resolving the Roam(DB-minted) vs Obsidian(page-level) tension +(`research/260614-logseq-deep-dive/findings.md` §2). **CRDT** shards +(Anytype/AFFiNE/AppFlowy) mint object/block IDs as part of the CRDT structure — fine- +grained, store-assigned (`research/260614-localfirst-workspaces-deep-dive/findings.md` +§6). +**Priority:** Later + +--- + +### UC-52 — Delegate derived views to a shard's native query engine + +**Actor:** Orchestrator +**Goal:** When a shard exposes a native query engine, compute derived views (backlinks, +recent changes, typed queries) by delegating to it instead of scanning the projection. +**Source:** roam, intent +**Notes:** In Roam, derived views *are* Datalog queries over the datom graph +(`research/260614-roam-deep-dive/findings.md` §4). Makes "native query" an adapter +capability the orchestrator can key off (vs. computing views itself over the +projection). Operationalizes the ZigZag "dimensions + rasters" insight +(`research/260614-zigzag-deep-dive/findings.md` §5) and relates to UC-05/UC-34. Obsidian +nuance: query can be an *ecosystem plugin* (Dataview), **not core** — so "native query" +is adapter/plugin-provided and must not be assumed +(`research/260614-obsidian-deep-dive/findings.md` §7). **Notion** ships a native +database **query API** (filters/sorts) — a strong delegation target +(`research/260614-notion-deep-dive/findings.md` §2, §4). **Logseq** shows the third path: +Datalog over a **derived** index built from plain files — neither native-DB nor plugin; +when no engine exists, shard-wiki can build the index itself (UC-63, +`research/260614-logseq-deep-dive/findings.md` §3). **Wikibase** is the far end: +**SPARQL** over an RDF projection with **federated `SERVICE`** cross-endpoint joins +(`research/260614-wikibase-deep-dive/findings.md` §2) — a graph-query tier above +datalog/filters, and `SERVICE` is itself a query-time federation primitive (UC-74). +**Priority:** Later + +--- + +### UC-54 — Define a page as a live query over the union + +**Actor:** Author +**Goal:** Author a page whose body is materialized from a saved query over the union +(e.g. "all open tasks", "all pages tagged X"), refreshed as the union changes. +**Source:** obsidian, roam, intent +**Notes:** The Obsidian **Dataview** (4.4M downloads) / **Tasks** (3.6M) pattern, and +Roam `{{query}}` — query-defined dynamic pages +(`research/260614-obsidian-deep-dive/findings.md` §7). Distinct from UC-44 (reference/ +span manifest) and UC-52 (delegating *computation* of an existing view): here the *page +itself* is a query. Open: core page type vs. adapter vs. reference-UI/plugin (findings +§11 Q2). May delegate execution to a shard's native query engine (UC-52). **Notion** +linked/filtered databases are the commercial instance — one row-set surfaced through many +filtered views (`research/260614-notion-deep-dive/findings.md` §2). +**Priority:** Later + +--- + +### UC-63 — Serve structured queries over a file-backed shard via a derived index + +**Actor:** Reader or orchestrator +**Goal:** Run structured queries (tasks, tagged blocks, typed properties) over a +file-backed shard that exposes no native query engine, using an index the orchestrator or +adapter builds and rebuilds from the files. +**Source:** logseq, intent +**Notes:** Logseq proves a **file-backed** store supports rich **Datalog** queries via a +**derived DataScript index** (files canonical, graph derived — +`research/260614-logseq-deep-dive/findings.md` §1, §3). The converse of UC-52 (delegate to +a *native* engine): here shard-wiki **builds** the index over the projection when none +exists. Operationalizes the ZigZag dimensions / Roam-Notion query model on a file shard. +Open: built by adapter (per-shard) or core (over the union); persisted vs rebuilt +(findings §10 Q2). Belongs to the T16 navigation layer + T11 capabilities. +**Priority:** Later + +--- + +### UC-74 — Graph-query the union (SPARQL) and federate queries across endpoints + +**Actor:** Reader / analyst +**Goal:** Query graph-capable shards with a **graph query language (SPARQL)** and **federate +queries across endpoints** (`SERVICE`) — a query-time cross-shard join distinct from +structural (fork/neighborhood) federation. +**Source:** wikiengines, intent +**Notes:** SPARQL over the RDF projection (Wikidata Query Service / Blazegraph) is the +**native-query far-end** above Roam/Logseq datalog and Notion filters (UC-52); `SERVICE` is +a **query-time federation** primitive beside fedwiki's structural federation (UC-72) +(`research/260614-wikibase-deep-dive/findings.md` §2). Open: union-level common query vs +pass-through to graph-capable shards. Feeds SHARD-WP-0002 native-query tiering; relates +UC-63 (derived index — WDQS is one). +**Priority:** Later + +## E. Knowledge work and collaboration *Patterns from c2 social conventions and yawex authoring workflows.* @@ -1182,6 +1301,8 @@ that do not exist yet. Markdown-first wikilink/red-link extension (yawex TRANSFORM) applies. **Priority:** MVP +--- + ### UC-09 — Sandbox first edit **Actor:** New contributor @@ -1191,6 +1312,8 @@ pages. **Notes:** c2 `WikiWikiSandbox`, `WelcomeVisitors` onboarding path. **Priority:** MVP +--- + ### UC-10 — Discussion to consensus document **Actor:** Contributor (often acting as WikiMaster) @@ -1202,6 +1325,8 @@ over stacked clarifications (`DocumentMode`, `GoodStyle`). Mechanism in core vs reference UI TBD. **Priority:** Later +--- + ### UC-11 — Distill experience into reusable knowledge **Actor:** Practitioner @@ -1212,6 +1337,8 @@ reusable artifacts (patterns, methods, checklists). pages (UC-15). Not an encyclopedia (`WikiIsNotWikipedia`). **Priority:** Later +--- + ### UC-12 — Practitioner field notes **Actor:** Contributor @@ -1222,6 +1349,8 @@ explicitly work-in-progress. UC-11; distinct from reference-grade documentation in `docs/` or `spec/`. **Priority:** MVP +--- + ### UC-13 — Community presence **Actor:** Visitor @@ -1232,6 +1361,8 @@ space. (`ArchitectureBlueprint` L1 Attributed mode). **Priority:** Later +--- + ### UC-14 — Self-curating knowledge base **Actor:** Community @@ -1242,6 +1373,8 @@ convergent deduplication rather than gatekeeping. shard-wiki adds Git history as structural safety net beyond social norms. **Priority:** MVP +--- + ### UC-15 — Create page from blueprint **Actor:** Author @@ -1256,6 +1389,8 @@ relation) inject an attribute set + structure into instances — blueprint-as-ty (`research/260614-trilium-deep-dive/findings.md` §3, links UC-67). **Priority:** Later +--- + ### UC-16 — Append or comment without full edit **Actor:** Author @@ -1266,9 +1401,7 @@ patch, comment, or append workflow. for read-only/remote shards; direct append where adapter allows. **Priority:** Later ---- - -## C. Discovery and navigation +## F. Discovery and navigation *Derived views and browse patterns from c2 and yawex.* @@ -1282,6 +1415,8 @@ for read-only/remote shards; direct append where adapter allows. at any scope. **Priority:** MVP +--- + ### UC-18 — BackLinks navigation **Actor:** Reader @@ -1290,6 +1425,8 @@ at any scope. **Notes:** Link-graph query. Strong core candidate for federated union (UC-05). **Priority:** Later +--- + ### UC-19 — All pages and site map browse **Actor:** Reader @@ -1299,6 +1436,8 @@ at any scope. `RoadMaps`. Namespace/path model affects presentation (UC-22). **Priority:** Later +--- + ### UC-20 — Full-text search **Actor:** Reader @@ -1308,6 +1447,8 @@ at any scope. adapter-provided indexing TBD. **Priority:** Later +--- + ### UC-21 — Serendipitous browse **Actor:** Reader @@ -1316,6 +1457,8 @@ adapter-provided indexing TBD. **Notes:** `RandomPages`, `VisualTour`, `LikePages`, `StartingPoints`. **Priority:** Later +--- + ### UC-22 — Namespace and path navigation **Actor:** Reader or author @@ -1333,6 +1476,8 @@ so there is no single canonical path (UC-66, `research/260614-trilium-deep-dive/findings.md` §2). **Priority:** Later +--- + ### UC-23 — Soft topic creation via red link **Actor:** Author @@ -1342,11 +1487,9 @@ so there is no single canonical path (UC-66, CommonMark wikilink + red-link extension. **Priority:** MVP ---- +## G. Provenance and page metadata -## D. Provenance and page metadata - -*yawex `Page::info` and c2 attribution norms.* +*yawex `Page::info`, c2 attribution norms, and statement-level provenance.* ### UC-24 — Inspect page provenance @@ -1365,6 +1508,8 @@ values coexist with a curation signal (UC-75, sub-page/per-assertion provenance even if MVP records it per page. **Priority:** Later +--- + ### UC-25 — Collaborative glossary and precise naming **Actor:** Community @@ -1381,6 +1526,23 @@ identities are part of the legacy identity surface the adapter must parse and tr --- +### UC-75 — Preserve statement-level provenance (references + rank) + +**Actor:** Core orchestrator +**Goal:** Preserve **provenance at the assertion level** — references and **rank** attached +to each *statement*, not just per page or per shard — so contradictory values can coexist +with a curation signal. +**Source:** wikiengines, intent +**Notes:** Wikibase attaches **references** (sources) and a **rank** +(`preferred`/`normal`/`deprecated`) to each statement +(`research/260614-wikibase-deep-dive/findings.md` §1, §5) — provenance granularity **finer** +than shard-wiki's per-page model, and the *structured* analogue of fedwiki's chorus (UC-72) +and "view multiple versions" (UC-27). The page model + coordination journal should **allow** +sub-page/per-assertion provenance even if MVP records per page. Enriches UC-24; feeds +SHARD-WP-0002 T12 + provenance model. +**Priority:** Later + + ## Traceability Dive-source markers (placed in the nearest existing column — usually **wikiengines** or