# 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>