shard-wiki/spec/UseCaseCatalog.md

# UseCaseCatalog

Status: **draft** · Date: 2026-06-08 · Updated: 2026-06-14

Promoted from `research/260608-c2-wiki-origins/`,
`research/260608-yawex-prior-art/`, `research/260608-federation-concepts/`,
`research/260608-wikiengines-overview/`, `research/260613-xwiki-deep-dive/`,
`research/260613-twiki-deep-dive/`, `research/260613-foswiki-deep-dive/`,
`research/260614-xanadu-deep-dive/`, `research/260614-zigzag-deep-dive/`,
`research/260614-roam-deep-dive/`, `research/260614-obsidian-deep-dive/`, and
`research/260614-notion-deep-dive/`.
See InfoTechPrimers on coulomb.social for use-case catalog conventions.

## Conventions

Each use case lists:

- **Actor** — who initiates the action
- **Goal** — observable outcome
- **Source** — research lineage (`c2`, `yawex`, `federation`, `wikiengines`, `intent`, or combined)
- **Notes** — shard-wiki-specific constraints or open design points

Priority hints: **MVP** = likely early value; **Later** = important but not first slice.

---

## A. Information space and federation

*shard-wiki orchestration scenarios (INTENT + yawex federation seeds).*

### UC-01 — Standalone open wiki (L0)

**Actor:** Anonymous contributor  
**Goal:** Read and write wiki pages with full history and no external dependencies.  
**Source:** intent, c2  
**Notes:** Ward Cunningham / c2-style open mode (`WhyWikiWorks`). Recovery via Git
history, not gatekeeping. Aligns with L0 in `spec/ArchitectureBlueprint.md`.
**Priority:** MVP

### UC-02 — Attach a shard to an information space

**Actor:** Maintainer  
**Goal:** Attach a repository, directory, or other backend as a shard of a root entity.  
**Source:** intent, yawex  
**Notes:** yawex `Conf::TestWiki / FriendsWiki` foreshadows multiple roots/shards.
Preserve shard sovereignty and adapter capability profile.  
**Priority:** MVP

### UC-03 — Project a remote shard page locally

**Actor:** Reader  
**Goal:** View a page from a remote or read-only shard as a local projection with
provenance and freshness visible.  
**Source:** intent, yawex  
**Notes:** yawex `VIRTUAL` state = projection/cache. Lazy projection; no silent
mutation.  
**Priority:** Later

### UC-04 — Overlay edit on read-only shard

**Actor:** Author  
**Goal:** Propose changes to a remote/read-only page as overlay, draft, or patch
before destructive apply.  
**Source:** intent, yawex  
**Notes:** yawex append/comment workflow; c2 ThreadMode → refactor pattern.
Overlay-before-mutation principle.  
**Priority:** Later

### UC-05 — Union derived views

**Actor:** Reader  
**Goal:** Navigate BackLinks, RecentChanges, AllPages, SiteMap, or Search across
all attached shards as a federated graph.  
**Source:** intent, c2, yawex  
**Notes:** Present on both c2 (community nerve center) and yawex core pages.
BackLinks over the union link-graph is the strongest core candidate; per-shard
vs union scope remains open (see UC-19–UC-21). ZigZag deep dive reframes these views
under one vocabulary: each is a **dimension + raster** (RecentChanges along `d.recent`,
AllPages along `d.alphabetical`, SiteMap as an H-view over the namespace dimensions),
navigable via UC-47 (`research/260614-zigzag-deep-dive/findings.md` §5). Note: the
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  
**Goal:** Read and write under role-based authorization with identity from an
external provider.  
**Source:** intent, yawex  
**Notes:** yawex htpasswd + per-topic `AccessControl` is prior art only;
shard-wiki delegates authentication, owns authorization
(`spec/ArchitectureBlueprint.md`). yawex's model traces to **TWiki's per-topic
`ALLOW/DENY TOPICVIEW/CHANGE/RENAME`** — the origin reference for shard-wiki's
optional per-page ACL at L4 (`research/260613-twiki-deep-dive/findings.md` §4).  
**Priority:** Later

### UC-07 — Detect and reconcile cross-shard divergence

**Actor:** Maintainer  
**Goal:** Identify when equivalent pages in different shards have diverged and
reconcile them under explicit policy.  
**Source:** intent  
**Notes:** Union without erasure — conflicts visible, not hidden. Complements
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  
**Goal:** Copy a page from a remote or read-only shard into a local writable
shard for independent editing, with provenance preserved.  
**Source:** federation, intent  
**Notes:** Fedwiki fork primitive. shard-wiki may realize as import, overlay
seed, or writable copy per policy — distinct from UC-04 (overlay without copy)
and UC-03 (projection only). Fork vs overlay vs import decided in
`SHARD-WP-0002`. Should record a **created-from genealogy edge** in the coordination
journal so the lineage is navigable as a dimension (UC-49,
`research/260614-zigzag-deep-dive/findings.md` §9).  
**Priority:** Later

### UC-27 — View multiple versions of equivalent page

**Actor:** Reader  
**Goal:** See coexisting versions of the same topic from different shards or
authors without collapsing them into one canonical page.  
**Source:** federation, intent  
**Notes:** Fedwiki "chorus of voices"; INTENT union without erasure. Equivalent-
page identity model TBD (`SHARD-WP-0002`) — Xanadu deep dive offers a path-independent
detection mechanism via content-identity / span-set intersection (UC-46,
`research/260614-xanadu-deep-dive/findings.md` §5, §8.2). Links UC-07 divergence
detection.  
**Priority:** Later

### UC-28 — Carry forward pages from closed or archived shard

**Actor:** Maintainer or author  
**Goal:** Selectively import or re-project valuable pages from an archived,
read-only, or retired shard into an active information space.  
**Source:** federation  
**Notes:** Caulfield bounded conversation / reverse bit-rot. Optional space
lifecycle policy. Complements UC-02 attach and UC-26 fork at scale. Obsidian's
**Importer** (1.4M) plugin (Evernote/Notion/Bear/Apple Notes → Markdown) shows demand
for importing from foreign tools (`research/260614-obsidian-deep-dive/findings.md` §7).  
**Priority:** Later

### UC-29 — Remix with portable attribution

**Actor:** Author  
**Goal:** Reuse content across shards or spaces with attribution and edit
history intact, without manual copy-paste.  
**Source:** federation, intent, xanadu  
**Notes:** Fedwiki journal travels with page; shard-wiki coordination journal +
per-shard history. Frictionless reuse principle (~15s not ~15min). Xanadu
**transcopyright**: a reference carries provenance *and reuse terms* with it, so
attribution/permission travel with the span — but reuse policy stays configurable, not
baked into the substrate (`research/260614-xanadu-deep-dive/findings.md` §6); links the
authz-in-core L0→L4 ladder decision. Remix should also record a **genealogy edge**
(UC-49) so reuse lineage is navigable, not just attributed.  
**Priority:** Later

### UC-30 — Time-bounded collaboration space

**Actor:** Facilitator  
**Goal:** Run a collaboration period on a dedicated information space or shard
subset, then archive it while allowing selective carry-forward.  
**Source:** federation  
**Notes:** Fedwiki "happening"; lifecycle is configurable policy, not a hard-
coded core behavior. Relates to UC-28.  
**Priority:** Later

### UC-31 — Subscribe to remote shard changes

**Actor:** Maintainer or reader  
**Goal:** Receive timely notice when pages change on attached remote shards,
triggering projection refresh or reconciliation review.  
**Source:** federation, intent  
**Notes:** ikiwiki pinger/pingee; ActivityPub Create/Update; polling fallback.
Transport is adapter concern; freshness surfaced in UC-24. XWiki deep dive adds a
concrete push transport: an engine event bus (`ObservationManager`
`DocumentUpdatedEvent`) consumed by a listener, vs polling REST history
(`research/260613-xwiki-deep-dive/findings.md` §2.5, §8 Q4). Notion adds **webhooks**
(2026) delivering page/database change events — a SaaS push transport, weighed against
eventual consistency and the rate limit (`research/260614-notion-deep-dive/findings.md`
§4).  
**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).  
**Priority:** Later

### UC-33 — Git-branch an information space

**Actor:** Maintainer  
**Goal:** Fork the coordination journal and attached shard configuration into a
divergent information space without destroying the original.  
**Source:** federation, intent  
**Notes:** ikiwiki wiki-branch pattern; Git-backed coordination per INTENT.
Space-level fork — distinct from UC-26 page-level fork.  
**Priority:** Later

### 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).  
**Priority:** Later

### UC-35 — Attach a shard with coarse write granularity

**Actor:** Maintainer  
**Goal:** Attach a backend whose unit of write is not the page — a single-file
wiki (TiddlyWiki) or a whole-space/DB-transaction engine — and have shard-wiki
respect that granularity instead of assuming per-page writes.  
**Source:** wikiengines, intent  
**Notes:** Capability-aware adapters: the **capability profile must encode write
granularity** (per-page / per-file / per-space / append-only). Overlay and
patch flows must adapt (findings §5 #1). Affects conflict scope and locking. Roam marks
the **fine extreme** — block-level writes (`block.create/update/move/delete`), the
opposite of TiddlyWiki's whole-file granularity
(`research/260614-roam-deep-dive/findings.md` §6).  
**Priority:** Later

### UC-36 — Supply a git-addressable history to an internal-history engine

**Actor:** Maintainer  
**Goal:** Attach an engine whose revisions live only in its own database
(Confluence, MediaWiki) and give the information space a portable, git-backed
history it otherwise lacks.  
**Source:** wikiengines, intent  
**Notes:** Many engines expose revisions but not portable, git-style history.
The **coordination journal** supplies the Git-addressable layer (INTENT). Open:
is the journal authoritative or a mirror reconciled back to the engine
(findings §6 Q3)? Complements UC-07 divergence and UC-24 provenance. XWiki's
internal RCS table (`xwikircs`) is a concrete instance
(`research/260613-xwiki-deep-dive/findings.md` §2.4). This UC is *supplementation*
(the engine's past is DB-locked); where history is already in an open file format
(TWiki RCS `.txt,v`) it can instead be **imported** — see UC-41. Demand evidence:
**Obsidian Git is a top-7 plugin (2.7M)** — users manually bolt portable git history
onto a vault that has none natively (`research/260614-obsidian-deep-dive/findings.md`
§5, §7), exactly the gap the coordination journal fills as core. **Notion** is the
closed-SaaS instance: internal page history bounded by plan, **not portable** and not
exported as git (`research/260614-notion-deep-dive/findings.md` §4) — a supplementation
case like Confluence/MediaWiki, not an import case.  
**Priority:** Later

### UC-37 — Attach a static engine export as a read-only backup shard

**Actor:** Maintainer  
**Goal:** Attach a one-shot export with no live origin — a MediaWiki XML dump, an
HTML mirror, or an archived/read-only C2 — as a read-only cache/backup/patch
target.  
**Source:** wikiengines, intent  
**Notes:** Graceful degradation — a frozen export is still a legitimate
participant. Distinct from UC-03 (live projection with a reachable origin) and
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  
**Goal:** Turn an existing wiki engine into a federation participant by hosting a
shard-wiki adapter *inside* the engine through its own extension interface, rather
than scraping it from outside.  
**Source:** wikiengines, intent  
**Notes:** Realizes INTENT *composable integration* — first UC for the **engine-side**
direction (others attach engines from outside). XWiki is the proof case: its
component model (`@Component` + role hint) can replace auth/storage/rights, its
REST API and `ObservationManager` give transport + change events, and UIX adds
surfacing — enough to host a high-fidelity adapter
(`research/260613-xwiki-deep-dive/findings.md` §3). Trade-off vs an external REST
adapter (needs deploy access, higher fidelity) is open (findings §8 Q3).
Generalizes beyond XWiki: TWiki's plugin handler API (`beforeSaveHandler`,
`afterRenameHandler`, REST handlers) is an equivalent host surface
(`research/260613-twiki-deep-dive/findings.md` §3). **Roam Depot** is the modern
template: an extension default-exports `onload`/`onunload` and drives
`window.roamAlphaAPI` read (`q`/`pull`) + write (`block.*`/`page.create`)
(`research/260614-roam-deep-dive/findings.md` §5) — note Roam's API runs *inside* the
client, so write-through requires in-engine hosting (findings §11 Q2).  
**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

**Actor:** Maintainer  
**Goal:** Attach a live engine whose content is plain files on disk — TWiki
`data/<Web>/<Topic>.txt`, DokuWiki pages, a Gollum/ikiwiki repo — by reading its
**backing store directly** as a folder shard, instead of (or alongside) going
through its runtime API.  
**Source:** wikiengines, intent  
**Notes:** One backend, **two attachment paths** with different fidelity/consistency:
the on-disk store (offline-capable, git-native for repo-backed engines, but risks
reading inconsistent state under a running engine) vs the runtime API (consistent,
respects engine logic, but requires the engine up). Capability profile must express
the choice (`research/260613-twiki-deep-dive/findings.md` §5–§6, §8 Q1). Distinct
from UC-37 (no live origin) and broader than UC-02's generic attach. Foswiki's
**PlainFile** store (timestamped whole-version copies, no RCS) is a cleaner
direct-attach target than RCS diffs (`research/260613-foswiki-deep-dive/findings.md`
§2.2). An **Obsidian vault** is the cleanest case of all — a plain Markdown folder,
Markdown-first and git-friendly — and uniquely **dual-attachable**: file-store direct
*or* via an in-app plugin adapter for write-through + live file events (UC-53,
`research/260614-obsidian-deep-dive/findings.md` §4, §10).  
**Priority:** Later

### UC-41 — Import an engine's native file history into the coordination journal

**Actor:** Maintainer  
**Goal:** When an engine already keeps history in an open file format (TWiki/yawex
RCS `.txt,v`), **import that history** into the Git-backed coordination journal
preserving authorship and timestamps — not just start a fresh journal going forward.  
**Source:** wikiengines, intent  
**Notes:** History *migration with fidelity*, distinct from UC-36 *supplementation*
(where the engine's past is locked in a DB and the journal can only begin now). Open:
is the imported history authoritative or a one-time backfill
(`research/260613-twiki-deep-dive/findings.md` §8 Q2)? Strengthens recoverability
(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.  
**Priority:** Later

### UC-43 — Tolerate a shard's storage-backend swap without losing identity

**Actor:** Maintainer  
**Goal:** Keep a shard attached, with its provenance and history intact, when its
underlying storage backend changes — e.g. a Foswiki wiki migrated RCS→PlainFile, or a
folder shard promoted into Git.  
**Source:** wikiengines, intent  
**Notes:** Foswiki proves backends are swappable under a stable identity via its
versioned `Foswiki::Store` interface (`research/260613-foswiki-deep-dive/findings.md`
§2). shard-wiki orchestration robustness: a shard's identity/attachment is **not** its
storage format. Open: detect the swap and preserve history across it (findings §9 Q3).
Relates to UC-40 (attach path) and UC-41 (history import) but is about *change under a
live attachment*, not initial attach.  
**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).  
**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).  
**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

**Actor:** Maintainer  
**Goal:** Attach a block-first, DB-backed graph tool (Roam-style) as a shard via its
query/CRUD API, mapping its blocks onto shard-wiki's Markdown page model without
flattening the structure.  
**Source:** roam, intent  
**Notes:** Roam's graph is a DataScript datom DB where a *page* is the node carrying
`:node/title` and nested *blocks* are addressable spans
(`research/260614-roam-deep-dive/findings.md` §2, §6). Clean mapping rule: titled node
= page, nested blocks = spans, attributes = sidecar metadata (honors UC-34 no-lossy-
flatten). DB-backed/API-attached path (like XWiki UC-38), **not** the file-store path
(UC-40). Write-through requires hosting the adapter inside the engine (Roam Depot),
else degrade to read/projection/overlay-target (findings §11 Q2). **Notion** is the
external-API variant of the same block-DB family: a server Postgres store with a real
**external** REST API, so write-through needs **no in-engine hosting** — but is bounded
by rate limits and eventual consistency (UC-57,
`research/260614-notion-deep-dive/findings.md` §4).  
**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).  
**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).  
**Priority:** Later

### UC-53 — Attach a local-first Markdown vault with a live concurrent native editor

**Actor:** Maintainer  
**Goal:** Attach an Obsidian-style local Markdown vault as a file-backed shard while its
own app continues to edit the files concurrently — watching for external changes,
re-projecting, and treating the app's config dir as opaque.  
**Source:** obsidian, intent  
**Notes:** Obsidian "file over app": vault = folder of `.md` + `.obsidian/` config;
files are canonical (`research/260614-obsidian-deep-dive/findings.md` §1). Cleanest
file-store attach (UC-40) — and uniquely **dual-mode**: zero-config direct attach
(read/projection/overlay) *or* an in-app adapter (Obsidian plugin) for write-through +
live `vault` events (UC-38, findings §4). Needs **external-writer tolerance**
(file-watch, re-project, conflict-with-live-app) distinct from multi-user write
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.  
**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

**Actor:** Maintainer  
**Goal:** Attach a closed, hosted SaaS (Notion-style) that has no file store and no
in-app plugin runtime, reachable only through its external REST API — honoring its rate
limits, eventual consistency, payload/pagination caps, and a scoped, revocable access
grant.  
**Source:** notion, intent  
**Notes:** Notion is external-REST-attachable with **no in-engine hosting** (contrast
Roam UC-50) but inside a tight operational envelope: ~3 req/s, eventual consistency,
recursive first-level-children fetch, and integrations that see **only explicitly
connected pages** (`research/260614-notion-deep-dive/findings.md` §4, §6). The capability
profile must encode this **operational envelope** and **scoped/revocable grant**;
projection is cache/poll/webhook, not a live read model. Best as projection/mirror/
overlay/backup; write-through possible but bounded. Links the authz-in-core decision and
"no silent remote mutation". Third attachment mode alongside file-store (UC-40) and
in-engine host (UC-38/50).  
**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`.  
**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

---

## B. Knowledge work and collaboration

*Patterns from c2 social conventions and yawex authoring workflows.*

### UC-08 — Quick idea capture

**Actor:** Contributor  
**Goal:** Capture a thought as a page and link to related pages, including ones
that do not exist yet.  
**Source:** c2  
**Notes:** c2 *incremental* and *open* design principles; Wiki = "quick web."
Markdown-first wikilink/red-link extension (yawex TRANSFORM) applies.  
**Priority:** MVP

### UC-09 — Sandbox first edit

**Actor:** New contributor  
**Goal:** Learn editing mechanics in a safe sandbox without affecting production
pages.  
**Source:** c2  
**Notes:** c2 `WikiWikiSandbox`, `WelcomeVisitors` onboarding path.  
**Priority:** MVP

### UC-10 — Discussion to consensus document

**Actor:** Contributor (often acting as WikiMaster)  
**Goal:** Refine a ThreadMode conversation into an unsigned DocumentMode page
that reflects community consensus.  
**Source:** c2  
**Notes:** ADD / EDIT / SPLIT / CAPTURE thread contributions; prefer rewrite
over stacked clarifications (`DocumentMode`, `GoodStyle`). Mechanism in core
vs reference UI TBD.  
**Priority:** Later

### UC-11 — Distill experience into reusable knowledge

**Actor:** Practitioner  
**Goal:** Turn field notes, threads, or project experience into durable,
reusable artifacts (patterns, methods, checklists).  
**Source:** c2, yawex  
**Notes:** c2 `PatternMode`, PPR "People, Projects & Patterns"; yawex blueprint
pages (UC-15). Not an encyclopedia (`WikiIsNotWikipedia`).  
**Priority:** Later

### UC-12 — Practitioner field notes

**Actor:** Contributor  
**Goal:** Maintain informal, subjective programming and project history that is
explicitly work-in-progress.  
**Source:** c2  
**Notes:** `InformalHistoryOfProgrammingIdeas`, `WorkInProgress`. Complements
UC-11; distinct from reference-grade documentation in `docs/` or `spec/`.  
**Priority:** MVP

### UC-13 — Community presence

**Actor:** Visitor  
**Goal:** Signal participation and discover who is active in the information
space.  
**Source:** c2  
**Notes:** c2 `RecentVisitors`, `PeopleIndex`. Optional attribution at L1+
(`ArchitectureBlueprint` L1 Attributed mode).  
**Priority:** Later

### UC-14 — Self-curating knowledge base

**Actor:** Community  
**Goal:** Improve collective quality through open editing, refactoring, and
convergent deduplication rather than gatekeeping.  
**Source:** c2  
**Notes:** `WhyWikiWorks`, `RefactorDontDelete`, `Convergent` design principle.
shard-wiki adds Git history as structural safety net beyond social norms.  
**Priority:** MVP

### UC-15 — Create page from blueprint

**Actor:** Author  
**Goal:** Instantiate a new page or topic structure from a template, duplicating
an agreed layout or subtree.  
**Source:** yawex  
**Notes:** yawex blueprint pages. Distinct from UC-08 (blank capture) and UC-10
(refactoring existing discussion). Obsidian's popular **Templater** (4.6M) / **QuickAdd**
(1.9M) plugins show templated creation is a top real-world need
(`research/260614-obsidian-deep-dive/findings.md` §7).  
**Priority:** Later

### UC-16 — Append or comment without full edit

**Actor:** Author  
**Goal:** Add material to a page without replacing the entire body — lightweight
patch, comment, or append workflow.  
**Source:** yawex, c2  
**Notes:** yawex append/comment; c2 ThreadMode ADD. Maps to overlay model (UC-04)
for read-only/remote shards; direct append where adapter allows.  
**Priority:** Later

---

## C. Discovery and navigation

*Derived views and browse patterns from c2 and yawex.*

### UC-17 — Change radar

**Actor:** Reader or maintainer  
**Goal:** See what changed recently across pages and who changed it.  
**Source:** c2, yawex  
**Notes:** c2 `RecentChanges`, `QuickChanges`, `RecentChangesJunkie`; yawex
`RecentChanges` core page. Union scope in UC-05; this UC covers the user need
at any scope.  
**Priority:** MVP

### UC-18 — BackLinks navigation

**Actor:** Reader  
**Goal:** Find pages that link to the current page.  
**Source:** c2, yawex  
**Notes:** Link-graph query. Strong core candidate for federated union (UC-05).  
**Priority:** Later

### UC-19 — All pages and site map browse

**Actor:** Reader  
**Goal:** Survey the full page inventory or hierarchical site structure.  
**Source:** c2, yawex  
**Notes:** yawex `AllPages`, `SiteMap` core pages; c2 `WikiList`, categories,
`RoadMaps`. Namespace/path model affects presentation (UC-22).  
**Priority:** Later

### UC-20 — Full-text search

**Actor:** Reader  
**Goal:** Find pages by content keyword or phrase.  
**Source:** c2, yawex  
**Notes:** yawex `SearchPage`; c2 `FindPage`, `SearchHelper`. Core vs
adapter-provided indexing TBD.  
**Priority:** Later

### UC-21 — Serendipitous browse

**Actor:** Reader  
**Goal:** Discover unexpected relevant pages without a specific search target.  
**Source:** c2  
**Notes:** `RandomPages`, `VisualTour`, `LikePages`, `StartingPoints`.  
**Priority:** Later

### UC-22 — Namespace and path navigation

**Actor:** Reader or author  
**Goal:** Resolve and navigate pages using relative (`../`), absolute (`/`), and
normalized paths within a topic hierarchy.  
**Source:** yawex  
**Notes:** yawex topics-as-directories; page-resolution state space is
inspiration only for federation design (not inherited as API). ZigZag deep dive: treat
the namespace hierarchy as **one dimension among many** (encoded left-child/right-sibling
as two zz-dimensions), not the privileged structure — consistent with mechanism over
policy; navigate it as one axis via UC-47 (`research/260614-zigzag-deep-dive/findings.md`
§4, §7.1).  
**Priority:** Later

### UC-23 — Soft topic creation via red link

**Actor:** Author  
**Goal:** Follow a link to a nonexistent page and create it on first write.  
**Source:** c2, yawex  
**Notes:** c2 `PageName?`; yawex red-`?` link semantics. TRANSFORM to
CommonMark wikilink + red-link extension.  
**Priority:** MVP

---

## D. Provenance and page metadata

*yawex `Page::info` and c2 attribution norms.*

### UC-24 — Inspect page provenance

**Actor:** Reader  
**Goal:** See source shard, modification time, freshness, editor attribution,
edit count, and whether the page has local overlays or diverges elsewhere.  
**Source:** yawex, c2, intent  
**Notes:** yawex `Page::info`; c2 optional `UserName` signing. INTENT explicit
provenance principle. Xanadu deep dive: provenance is *structural*, not decorative —
content remembers where it came from and where it is reused (UC-45), built into the
storage model rather than added after the fact
(`research/260614-xanadu-deep-dive/findings.md` §4, §8.1).  
**Priority:** Later

### UC-25 — Collaborative glossary and precise naming

**Actor:** Community  
**Goal:** Build a shared vocabulary of precise page titles and linked terms that
reduce ambiguity across the information space.  
**Source:** c2, yawex  
**Notes:** c2 flat namespace + `WikiWord` / `Precise` principle; yawex
CamelCase and `[[free links]]`. Markdown-first link semantics TBD.  
**Priority:** Later

---

## Traceability

| UC | c2 research | yawex research | federation research | wikiengines research | INTENT |
|----|-------------|----------------|---------------------|----------------------|--------|
| UC-01 | ✓ | | | | ✓ |
| UC-02 | | ✓ | | | ✓ |
| UC-03 | | ✓ | ✓ | | ✓ |
| UC-04 | ✓ | ✓ | ✓ | | ✓ |
| UC-05 | ✓ | ✓ | ✓ | | ✓ |
| UC-06 | | ✓ | | | ✓ |
| UC-07 | | | ✓ | | ✓ |
| UC-26 | | | ✓ | | ✓ |
| UC-27 | | | ✓ | | ✓ |
| UC-28 | | | ✓ | | |
| UC-29 | | | ✓ | | ✓ |
| UC-30 | | | ✓ | | |
| UC-31 | | | ✓ | | ✓ |
| UC-32 | | | ✓ | | ✓ |
| UC-33 | | | ✓ | | ✓ |
| UC-34 | | | | ✓ | ✓ |
| UC-35 | | | | ✓ | ✓ |
| UC-36 | | | | ✓ | ✓ |
| UC-37 | | | | ✓ | ✓ |
| UC-38 | | | | ✓ | ✓ |
| UC-39 | | | | ✓ | ✓ |
| UC-40 | | | | ✓ | ✓ |
| UC-41 | | | | ✓ | ✓ |
| UC-42 | | | | ✓ | ✓ |
| UC-43 | | | | ✓ | ✓ |
| UC-44 | | | ✓† | | ✓ |
| UC-45 | | | ✓† | | ✓ |
| UC-46 | | | ✓† | | ✓ |
| UC-47 | | | ‡ | | ✓ |
| UC-48 | | | ‡ | | |
| UC-49 | | | ‡ | | ✓ |
| UC-50 | | | | § | ✓ |
| UC-51 | | | | § | ✓ |
| UC-52 | | | | § | ✓ |
| UC-53 | | | | ¶ | ✓ |
| UC-54 | | | | ¶ | ✓ |
| UC-55 | | | | ¶ | ✓ |
| UC-56 | | | | ¶ | ✓ |
| UC-57 | | | | ◊ | ✓ |
| UC-58 | | | | ◊ | ✓ |
| UC-59 | | | | ◊ | ✓ |
| UC-08 | ✓ | | |
| UC-09 | ✓ | | |
| UC-10 | ✓ | | |
| UC-11 | ✓ | ✓ | |
| UC-12 | ✓ | | |
| UC-13 | ✓ | | |
| UC-14 | ✓ | | ✓ |
| UC-15 | | ✓ | |
| UC-16 | ✓ | ✓ | |
| UC-17 | ✓ | ✓ | |
| UC-18 | ✓ | ✓ | |
| UC-19 | ✓ | ✓ | |
| UC-20 | ✓ | ✓ | |
| UC-21 | ✓ | | |
| UC-22 | | ✓ | |
| UC-23 | ✓ | ✓ | |
| UC-24 | ✓ | ✓ | ✓ |
| UC-25 | ✓ | ✓ | |

### c2 synthesis mapping

| Research ID | Catalog UC |
|-------------|------------|
| UC-C2-01 Quick idea capture | UC-08 |
| UC-C2-02 Collaborative glossary | UC-25 |
| UC-C2-03 Discussion → consensus doc | UC-10 |
| UC-C2-04 Pattern mining | UC-11 |
| UC-C2-05 Community guest book | UC-13 |
| UC-C2-06 Change radar | UC-17 |
| UC-C2-07 Self-curating knowledge base | UC-14 |
| UC-C2-08 Sandbox learning | UC-09 |
| UC-C2-09 Serendipitous browse | UC-21 |
| UC-C2-10 Practitioner field notes | UC-12 |
| UC-C2-11 Team memory for methods | UC-11, UC-12 |
| UC-C2-12 Soft creation of missing topics | UC-23 |

### yawex KEEP mapping

| yawex KEEP item | Catalog UC |
|-----------------|------------|
| Derived views (BackLinks, RecentChanges, AllPages, SiteMap, Search) | UC-05, UC-17–UC-20 |
| Topic = namespace hierarchy | UC-22 |
| Append/comment workflow | UC-04, UC-16 |
| Blueprint pages | UC-15 |
| Provenance hooks | UC-24 |
| Page classes (local/global/virtual) | UC-02, UC-03 (shard roles) |
| Wikilink / red-link semantics | UC-08, UC-23, UC-25 |

### federation research mapping

| Research ID (findings §7) | Catalog UC |
|---------------------------|------------|
| UC-FED-01 Fork page from remote shard | UC-26 |
| UC-FED-02 View multiple versions of equivalent page | UC-27 |
| UC-FED-03 Carry forward from closed/archived shard | UC-28 |
| UC-FED-04 Remix with portable attribution | UC-29 |
| UC-FED-05 Time-bounded collaboration space | UC-30 |
| UC-FED-06 Subscribe to remote shard changes | UC-31 |
| UC-FED-07 Transclude remote span | UC-32 |
| UC-FED-08 Git-branch information space | UC-33 |

### wikiengines mapping

| Engine-landscape finding | Catalog UC |
|--------------------------|------------|
| Structured/semantic engines (Semantic MediaWiki, XWiki) — pages as queryable objects | UC-34 |
| Coarse write granularity (TiddlyWiki single-file; whole-space DB writes) | UC-35 |
| Internal-only revision history (Confluence, MediaWiki) needs portable git history | UC-36 |
| Static exports / read-only archives (MediaWiki XML dump, archived C2, HTML mirror) | UC-37 |
| Engine hosts adapter via native extension API (XWiki components/REST/UIX) | UC-38 |
| Wiki-as-application-platform, bodiless typed pages (XWiki AppWithinMinutes/XObjects) | UC-39 |
| Attach a file-backed engine's on-disk store directly (TWiki data dir, DokuWiki) | UC-40 |
| Import an engine's native file history (TWiki RCS `.txt,v`) into the journal | UC-41 |
| Lossless syntax translation for a non-Markdown shard (Foswiki WysiwygPlugin TML↔HTML) | UC-42 |
| Tolerate a shard's storage-backend swap (Foswiki RCS↔PlainFile) under stable identity | UC-43 |

Note: the landscape scan mostly **reinforced** existing UCs and the L0→L4 ladder
rather than adding scenarios — its primary yield is adapter-contract constraints
(`research/260608-wikiengines-overview/findings.md` §3, §5), tracked in
`workplans/SHARD-WP-0002-federation-architecture.md`. UC-34–UC-37 are the
attachment scenarios it surfaced. UC-38–UC-39 come from the **XWiki deep dive**
(`research/260613-xwiki-deep-dive/findings.md` §7); UC-40–UC-41 from the **TWiki
deep dive** (`research/260613-twiki-deep-dive/findings.md` §7), which also enriched
UC-06 (TWiki per-topic ACL → yawex), UC-34 (file-embedded `%META%`), UC-36 (RCS vs
DB history), and UC-38 (TWiki plugin handlers as an adapter host). UC-42–UC-43 come
from the **Foswiki deep dive** (`research/260613-foswiki-deep-dive/findings.md` §8),
which also enriched UC-39 (MetaDataPlugin multi-record), UC-40 (PlainFile store), and
logged the `Foswiki::Store` versioned interface as **adapter-contract prior art** for
`SHARD-WP-0002` (no UC — architecture).

### xanadu mapping

(† UC-44–UC-46 are placed in the **federation** matrix column as the nearest existing
source; their true lineage is the **Xanadu deep dive**,
`research/260614-xanadu-deep-dive/findings.md`.)

| Xanadu mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| EDL/xanadoc — document as a manifest of span references, not content (§2) | UC-44 |
| Content "knowably in more than one place," remembers its appearances (§4) | UC-45 |
| Version/document comparison by span-set intersection, content identity (§5) | UC-46 |
| Content-identity, bidirectional transclusion (§4) | UC-32 (enriched) |
| Path-independent equivalence detection for parallel versions (§5) | UC-27 (enriched) |
| Transcopyright — reuse terms travel with the reference (§6) | UC-29 (enriched) |
| Structural provenance — content remembers origin and reuse (§4, §8.1) | UC-24 (enriched) |

Note: Xanadu is **conceptual prior art, not a candidate shard backend** — it never
shipped at scale and there is nothing to attach. Its yield is *mechanism*:
**reference-not-copy** documents (validating projection + overlay + union),
content-identity transclusion, and the still-open **portable span-address** problem
(tumblers), logged as adapter-contract architecture for `SHARD-WP-0002` (span
addressing as an adapter capability; content fingerprint; composition manifests;
reuse-terms metadata — `research/260614-xanadu-deep-dive/findings.md` §10). The dive
also recorded **design-bug boundaries**: shard-wiki **rejects** Xanadu's
single-global-docuverse premise, single-canonical-instance model, and baked-in economic
policy (findings §8.2), as these violate shard sovereignty, parallel-version support
(UC-27), and mechanism-over-policy.

### zigzag mapping

(‡ UC-47–UC-49 are placed in the **federation** matrix column as the nearest existing
source; their true lineage is the **ZigZag deep dive**,
`research/260614-zigzag-deep-dive/findings.md`.)

| ZigZag / zzstructure mechanism (findings §) | Catalog UC |
|---------------------------------------------|------------|
| Each relationship is a first-class **dimension**; a page is a cell at many ranks (§2, §5) | UC-47 |
| **H-view** — pivot two dimensions into a cross-tab (§3) | UC-48 |
| **Genealogy** as a functional dimension fitting a zz-rank (§4, §5) | UC-49 |
| Hierarchy is **one dimension among many** (left-child/right-sibling) (§4, §7.1) | UC-22 (enriched) |
| Derived views = **dimensions + rasters** under one vocabulary (§5) | UC-05 (enriched; anchors UC-17–UC-20) |
| Fork/remix records a navigable genealogy edge (§9) | UC-26, UC-29 (enriched) |
| **Clone** = "same content in many places" — converges with transclusion (§5) | links UC-32, UC-44/45 |

Note: ZigZag is **a data model + visualization paradigm, not a candidate shard
backend.** Recommendation recorded in the dive: adopt zzstructure as a **navigation /
visualization / indexing lens** — a *derived dimensional projection* over the union,
like BackLinks today — and **reject it as the storage substrate**
(`research/260614-zigzag-deep-dive/findings.md` §6, §7.2). Git and sovereign shards
remain canonical (INTENT Stability Note). The many-to-many hyperlink graph does **not**
fit zzstructure's one-neighbour-per-dimension rule and stays a separate graph index.
Architecture logged for `SHARD-WP-0002`: a dimensional projection layer; genealogy
edges in the coordination journal; clone↔transclusion as a possible shared primitive
(findings §9). Pairs with the Xanadu dive (clone ↔ transclusion convergence).

### roam mapping

(§ UC-50–UC-52 are placed in the **wikiengines** matrix column as the nearest existing
source — Roam is a shipped tool — but their true lineage is the **Roam deep dive**,
`research/260614-roam-deep-dive/findings.md`.)

| Roam mechanism (findings §) | Catalog UC |
|-----------------------------|------------|
| Block-graph DataScript DB; page = `:node/title` node, blocks = spans (§2, §6) | UC-50 |
| `:block/uid` — shipped stable sub-page address (§2, §7) | UC-51 |
| Derived views = Datalog queries over the graph (§4) | UC-52 |
| Block embeds = shipped live transclusion by uid (§3) | UC-32 (enriched; + UC-44/45) |
| `key:: value` attributes + Datalog = structured/typed pages (§3, §4) | UC-34 (enriched; + UC-39) |
| Roam Depot `onload/onunload` + `roamAlphaAPI` = engine-hosts-adapter template (§5) | UC-38 (enriched) |
| Block-level write granularity = the fine extreme (§6) | UC-35 (enriched) |
| Hosted history is internal-only, not portable Git (§6, §8.2) | links UC-36 |

Note: Roam is the **modern bookend** to the Nelson dives — where Xanadu and ZigZag are
unbuilt ideals, Roam *shipped* fine-grained addressing, transclusion, bidirectional
links, and a queryable structured space. Its payoff is **empirical evidence** on
shard-wiki's open questions (span addressing is tractable via native block IDs;
transclusion is a data-layer capability; derived views are queries —
`research/260614-roam-deep-dive/findings.md` §7). **Boundary recorded:** Roam is *one
candidate shard* — DB-backed / API-attached (the XWiki family, not the file-store
family), block-first, with no portable Git history — **mapped into** shard-wiki's
Markdown-first page model, not adopted as a substrate and never the federation layer
(findings §8.2). Architecture logged for `SHARD-WP-0002` (T14): native-span-ID and
native-query capabilities, block↔page mapping, and Roam as a second
engine-hosts-adapter exemplar alongside XWiki.

### obsidian mapping

(¶ UC-53–UC-56 are placed in the **wikiengines** matrix column as the nearest existing
source — Obsidian is a shipped tool — but their true lineage is the **Obsidian deep
dive**, `research/260614-obsidian-deep-dive/findings.md`.)

| Obsidian mechanism (findings §) | Catalog UC |
|---------------------------------|------------|
| File-over-app vault; cleanest file-backed Markdown shard, dual-attachable (§1, §4) | UC-53 (new); enriches UC-40, UC-02, UC-38 |
| Dataview/Tasks: a page materialized from a query (§7) | UC-54 (new) |
| Excalidraw/Canvas/attachments: non-Markdown content (§7) | UC-55 (new) |
| Obsidian Publish/Quartz: outbound publish (§7) | UC-56 (new) |
| In-file `^block-id` / heading anchors = git-diffable opt-in span IDs (§2) | UC-51 (enriched) |
| YAML frontmatter/properties = git-diffable in-file structured data (§3) | UC-34 (enriched) |
| Git plugin (top-7) = bolt-on portable history (§5, §7) | UC-36 (enriched) |
| Query is a plugin (Dataview), not core (§7) | UC-52 (enriched) |
| Importer plugin = import from foreign tools (§7) | UC-28 (enriched) |
| Templater/QuickAdd = templated creation (§7) | UC-15 (enriched) |
| MetadataCache: files-canonical / index-derived (§1, §6) | reinforces UC-05/17–20 derived-view model |

#### Plugin-popularity → use-case signal

Per the research brief (let ecosystem popularity inform the catalog). All-time download
ranks read as **demand evidence** — full table in
`research/260614-obsidian-deep-dive/findings.md` §7. Headlines:

- **#1 is drawings** (Excalidraw 6.4M) → non-Markdown content is a *primary* real-world
  use, not an edge case → **UC-55**.
- **Query-as-DB** (Dataview 4.4M, Tasks 3.6M) is top-tier but an *add-on* → query is an
  adapter/plugin capability (**UC-52**) and motivates query-defined pages (**UC-54**).
- **Git is top-7** (2.7M) → users manually bolt on portable history → direct demand for
  the coordination journal (**UC-36**).
- **Sync-to-anywhere** (Remotely Save 2.0M: S3/Dropbox/OneDrive/GDrive/WebDAV) →
  demand to connect a vault to the heterogeneous backends INTENT targets — while
  reaffirming the **not-a-file-sync-daemon** boundary (attach as shards, don't mirror).

Note: an Obsidian vault is **one file-backed candidate shard** — the cleanest,
INTENT-named, and the file-store counterpart to the DB-backed Roam shard — mapped into
the Markdown-first page model; **not** the federation layer and **not** a file-sync
target (`research/260614-obsidian-deep-dive/findings.md` §8.2). Architecture logged for
`SHARD-WP-0002` (T14): dual attachment mode, consume-native-derived-index capability,
non-Markdown content types in the page model, outbound publish, external-writer
tolerance.

### notion mapping

(◊ UC-57–UC-59 are placed in the **wikiengines** matrix column as the nearest existing
source — Notion is a shipped tool — but their true lineage is the **Notion deep dive**,
`research/260614-notion-deep-dive/findings.md`.)

| Notion mechanism (findings §) | Catalog UC |
|-------------------------------|------------|
| Closed hosted SaaS, external-REST-only, rate-limited/eventually-consistent, scoped grant (§4, §6) | UC-57 (new) |
| Database = schema + typed properties + relations + rollups + views (§2) | UC-58 (new) |
| Proprietary block/rich-text, lossy to Markdown (§3) | UC-59 (new) |
| Per-block UUID v4 via REST = store-minted span address (§1) | UC-51 (enriched) |
| Server Postgres + external REST API = block-DB without in-engine hosting (§4) | UC-50 (enriched) |
| Database query API; filtered/linked DBs (§2, §4) | UC-52, UC-54 (enriched) |
| Database-as-pages apex; typed records + relations (§2) | UC-34, UC-39 (enriched) |
| Webhooks (2026) as push transport (§4) | UC-31 (enriched) |
| Internal-only page history, not portable (§4) | UC-36 (enriched) |
| Publish-to-web outbound (§4) | UC-56 (enriched) |
| Scoped, revocable per-integration grant; no silent mutation (§6) | UC-57 + [[shard-wiki-auth-in-core-decision]] |

Note: Notion is the **closed/hosted/schema-rich** extreme and the dive that stress-tests
*graceful degradation*, *no silent remote mutation*, and *Markdown-first that must
degrade*. It adds the **third attachment mode** — external-API-only (full write-through
without in-engine hosting, but bounded by rate limits and eventual consistency) —
alongside file-store (UC-40) and in-engine host (UC-38/50). It also *enforces* no silent
mutation via scoped, revocable per-integration page grants
(`research/260614-notion-deep-dive/findings.md` §6). **Boundary recorded:** one
external-API candidate shard — best as projection/mirror/overlay/backup — not a
substrate and not the federation layer. Architecture logged for `SHARD-WP-0002` (T14):
an operational-envelope capability section (rate limit, consistency class, payload caps,
push-vs-poll), access-grant semantics, a translation-fidelity capability, and the
three-way attachment-mode taxonomy.

---

## Open questions

1. Which UC items are **MVP for L0 standalone** vs requiring federation or L2+?
2. Which derived views (UC-05, UC-17–UC-20) are **core orchestrator** vs
   **adapter-provided**?
3. Do c2 collaboration patterns (UC-10, UC-14) belong in **core**, **reference
   UI**, or **`wiki/` social convention** only?
4. Should UC-12 and `WikiIsNotWikipedia` be elevated into
   `ProductRequirementsDocument.md` as explicit product identity?
5. Which federation UCs (UC-26–UC-33) are **MVP** vs deferred until
   `SHARD-WP-0002` architecture decisions land?
6. Does UC-32 (transclusion) belong in core orchestrator or adapter/UI layer?
7. Is the **dimensional/zzstructure model** (UC-47/48) a public navigation API and UI
   paradigm, or only an internal organizing concept for the derived views?
8. How is the **many-to-many link graph** reconciled with the rank-based dimensional
   model — clones, a parallel graph index, or both? (ZigZag dive §10.)
9. Is **in-engine adapter hosting** (e.g. a Roam Depot extension for write-through) an
   accepted deployment mode generally, or do we restrict API-only backends to
   read/projection/overlay-target? (Roam dive §11 Q2; ties UC-38, UC-50.)
10. How does shard-wiki represent **non-Markdown content** (UC-55) — typed asset with a
    Markdown stub, opaque blob with provenance, or a pluggable content-type registry?
11. Is a **query-defined page** (UC-54) a core page type, an adapter feature, or a
    reference-UI/plugin concern? (Shared with catalog Q7.)
12. Is **external-API-only write-through** under a tight rate limit (Notion) viable at
    wiki scale, or do we default such shards to read/projection/overlay/backup? (Notion
    dive §10 Q1; ties UC-57.)
13. How are **inter-database relations** (UC-58) represented in the union — typed links
    in the link graph, a separate relation index (cf. ZigZag many-to-many), or both?