tegwick
6ccf349209
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>
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 anmldocAST 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:: valueproperties,{{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.