research: Logseq deep dive (block-graph on plain Markdown files, in-file block IDs, derived Datalog index); UC-62/63

Occupies the point the other modern tools leave empty: block-graph
semantics (UUID-addressable, embeddable, queryable blocks) stored as plain
Markdown/Org files on disk, with a DataScript graph derived from the files
(files canonical, index derived). The bridge between Roam (block-DB) and
Obsidian (file-over-app). Headline finding: Logseq resolves the
addressing-spectrum tension — block-level addressing that is also
git-diffable in-file text (id:: property) — and proves a file-backed shard
can serve rich Datalog queries via a derived index. Also: file->SQLite
"DB graph" migration is a live UC-43 (substrate swap under stable
identity); whiteboards = non-Markdown content; dual-attachable (file-store
direct with a Logseq format profile, or in-app plugin). Added UC-62
(attach block-graph-on-plain-files shard), UC-63 (serve structured
queries over a file shard via a derived index shard-wiki builds — converse
of UC-52); enriched UC-32/34/43/50/51/52/55. Catalog now 63 UCs.
Architecture for SHARD-WP-0002 T11/T14/T16: Logseq format profile,
derived-query-index capability, substrate-migration tolerance, in-file
block addressing as the T16 span-address target.

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

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

@@ -0,0 +1,50 @@
+# 260614 — Logseq deep dive (block-graph semantics on plain Markdown files)
+
+Date: 2026-06-14
+
+## What this is
+
+A focused study of **Logseq** — the open-source, local-first outliner — read through
+shard-wiki's lens. Logseq occupies the point the other modern tools leave empty:
+**block-graph semantics (UUID-addressable, embeddable, queryable blocks) stored as plain
+Markdown/Org files on disk**, with a DataScript graph **derived** from those files. It is
+the bridge between **Roam** (block-graph, client-DB) and **Obsidian** (file-over-app,
+page-level), and it resolves a tension the synthesis flagged: block-level addressing
+*that is also git-diffable text*.
+
+Distinctive material:
+- **Architecture** — files canonical (`pages/`, `journals/` MD/Org); a DataScript graph
+  **derived** via an `mldoc` AST parse; a DB Worker now manages **both DataScript and
+  SQLite** (the file→DB migration)
+- **Block-graph in the file text** — block IDs as in-file `id:: <uuid>` properties,
+  `((uuid))` refs, `key:: value` properties, `{{embed}}` transclusion, the outline tree
+  (indent/zoom/move-subtree) — all git-diffable
+- **Queries** — `{{query}}` + advanced **Datalog** over the derived graph
+  (`logseq.DB.datascriptQuery`)
+- **Extension** — plugin API (`logseq.App/Editor/DB/Git/UI/Assets/FileStorage`),
+  marketplace (~486 plugins); dual-attachable (file-store direct *or* in-app plugin)
+- **Trajectory** — migrating from Markdown-files to a SQLite "DB graph" (a live UC-43)
+
+## Contents
+
+| Path | Role |
+|------|------|
+| `findings.md` | Architecture, in-file block-graph, Datalog queries, plugin API, file→DB migration, capability profile, INTENT mapping, UC seeds, architecture notes, sources |
+
+## Status
+
+Initial deep dive complete. Two new use cases promoted to `spec/UseCaseCatalog.md`
+(UC-62 attach a block-graph-on-plain-files shard with in-file block IDs/properties +
+outline tree + derivable query index; UC-63 serve structured queries over a file-backed
+shard via a derived index the orchestrator/adapter builds); UC-32/34/43/50/51/52/55
+enriched. Logged for `SHARD-WP-0002` (T11/T14/T16): a Logseq **format profile** for
+file-store adapters, a **derived-query-index** capability, **substrate-migration
+tolerance**, and **in-file block addressing** as the concrete T16 span-address target.
+
+**Key takeaway recorded:** Logseq resolves the addressing-spectrum tension — block-level
+addressing **and** git-diffable in-file text (`id::`) — and proves a file-backed shard
+can support rich Datalog queries via a **derived** index (files canonical, graph
+derived). **Boundary:** one block-graph-on-files candidate shard (the addressing sweet
+spot), best attached file-store-direct with a format profile; not the federation layer;
+substrate is migrating file→SQLite.
+</content>