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