generated from coulomb/repo-seed
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>
50 lines
2.6 KiB
Markdown
50 lines
2.6 KiB
Markdown
# 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>
|