research: Roam Research deep dive (block-graph DataScript DB, transclusion, datalog, Roam Depot extension API); UC-50/51/52

The modern bookend to the Xanadu/ZigZag dives: where those are unbuilt
ideals, Roam shipped fine-grained addressing (:block/uid), live
transclusion (block embeds), bidirectional links, and a queryable
structured space (DataScript datoms + Datalog). Studied as a candidate
DB-backed/API-attached shard (XWiki family) and as a concrete
engine-hosts-adapter surface (Roam Depot onload/onunload over
window.roamAlphaAPI). Added UC-50 (attach block-graph DB shard, block<->page
mapping), UC-51 (adopt native span IDs as portable span addresses), UC-52
(delegate derived views to a shard's native query engine); enriched
UC-32/34/35/38. Boundary: Roam is one candidate shard mapped into the
Markdown-first page model, not a substrate and not the federation layer.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

research/260614-roam-deep-dive/README.md

@@ -0,0 +1,49 @@
+# 260614 — Roam Research deep dive (the block graph as a queryable database + extension API)
+
+Date: 2026-06-14
+
+## What this is
+
+A focused study of **Roam Research** — core architecture and extension structure —
+read through shard-wiki's lens. Roam is the **modern bookend** to the two Nelson dives:
+where Xanadu (`research/260614-xanadu-deep-dive/`) and ZigZag
+(`research/260614-zigzag-deep-dive/`) are *unbuilt ideals*, Roam **shipped** stable
+fine-grained addressing, transclusion, bidirectional links, and a queryable structured
+space to a mainstream audience.
+
+Distinctive material:
+- **Data model** — the entire graph is a client-side **DataScript** (Datomic-like) DB
+  of **datoms** (EAV); every paragraph and page is a **block** entity with a stable
+  nine-character **`:block/uid`**, `:block/string`, `:block/refs`, `:block/page`,
+  pages marked by `:node/title`
+- **References & transclusion** — `[[Page]]`/`#tag`/`((uid))` create `:block/refs`
+  edges; **block embeds** are working transclusion; linked vs unlinked references
+- **Querying** — Datalog (`:q`/`:pull`); derived views are queries over the graph
+- **Extension architecture** — **Roam Depot** (`extension.js` `onload`/`onunload`,
+  manifest, `extensionAPI` settings) over **`window.roamAlphaAPI`** read (`q`/`pull`) +
+  write (`block.create/update/move/delete`, `page.create`) — a concrete
+  *engine-hosts-adapter* (UC-38) surface
+
+## Contents
+
+| Path | Role |
+|------|------|
+| `findings.md` | Data model, references/transclusion, Datalog, extension API, Roam-as-shard capability profile, evidence on shard-wiki's open questions, INTENT mapping, UC seeds, architecture notes, sources |
+
+## Status
+
+Initial deep dive complete. Three new use cases promoted to `spec/UseCaseCatalog.md`
+(UC-50 attach a block-graph DB shard with block↔page mapping, UC-51 adopt native
+block/span IDs as portable span addresses, UC-52 delegate derived views to a shard's
+native query engine); UC-32/34/35/38 enriched. Logged for
+`workplans/SHARD-WP-0002-federation-architecture.md` (T14): native-span-ID and
+native-query capabilities, block↔page mapping, and Roam as a second DB-backed /
+engine-hosts-adapter exemplar alongside XWiki.
+
+**Key payoff recorded:** Roam empirically answers the Nelson dives' open questions —
+fine-grained addressing is tractable (block UIDs), transclusion is a data-layer
+capability over an addressable union, and derived views are queries over a structured
+space. **Boundary:** Roam is *one candidate shard* (DB-backed/API-attached, block-first,
+no portable Git history), mapped into shard-wiki's Markdown-first page model — not a
+substrate and not the federation layer.
+</content>