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