tegwick
dfff9ab42e
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>
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/refsedges; 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.jsonload/onunload, manifest,extensionAPIsettings) overwindow.roamAlphaAPIread (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.