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>
2026-06-14 15:27:37 +02:00
parent e00c160a43
commit 6ccf349209
5 changed files with 396 additions and 12 deletions
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -19,9 +19,9 @@ Learnings update both SCOPE and INTENT where necessary.
 |-------|-------|
 | Code | Python package scaffold (`src/shard_wiki/`, smoke tests only) |
 | Intent | `INTENT.md` established; authorization-in-core amendments drafted |
-| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin deep dives & shard-spectrum synthesis (`research/260614-*/`) |
+| Research | yawex prior art; c2 origins; federation concepts; wikiengines overview (`research/260608-*/`); XWiki/TWiki/Foswiki deep dives (`research/260613-*/`); Xanadu + ZigZag + Roam + Obsidian + Notion + Joplin + Logseq deep dives & shard-spectrum synthesis (`research/260614-*/`) |
 | Demand | NetKingdom integration asks captured, not yet negotiated |
-| Spec | Architecture blueprint drafted; UseCaseCatalog 61 UCs from research; PRD/TSD scaffolds |
+| Spec | Architecture blueprint drafted; UseCaseCatalog 63 UCs from research; PRD/TSD scaffolds |
 | Work | `SHARD-WP-0001` active (6 tasks); `SHARD-WP-0002` active (16 tasks: T1–T10 federation + T11–T16 adapter contract) |

 ## In Scope (today)
--- a/research/260614-logseq-deep-dive/README.md
+++ b/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>
--- a/research/260614-logseq-deep-dive/findings.md
+++ b/research/260614-logseq-deep-dive/findings.md
@@ -0,0 +1,246 @@
+# Findings — Logseq: block-graph semantics on plain Markdown files
+
+Date: 2026-06-14
+Source kind: **modern shipped product** — an open-source, local-first outliner; a
+*candidate shard* occupying the point none of the prior tools do: **block-graph + file-
+over-app**
+Lens: shard-wiki — the convergence of block-level addressing with git-diffable files, a
+derived query index over canonical files, and a live file→DB storage migration
+
+> Why Logseq matters distinctly. The modern-tool dives staked out the corners: **Roam**
+> = block-graph but client-DB / in-app-API / store-minted UUID; **Obsidian** =
+> file-over-app but page-level / path-addressed (block `^id` opt-in); **Notion** =
+> block-graph but closed hosted DB / external-API. **Logseq sits in the middle they
+> leave empty: block-graph *semantics* (UUID-addressable, embeddable, queryable blocks)
+> stored as *plain Markdown/Org files on disk you own*, with a DataScript index
+> **derived** from those files.** It is the system that proves you do not have to choose
+> between Roam's fine-grained addressing and Obsidian's file sovereignty — you can have
+> block-level addressing *that is also git-diffable text*. That resolves a tension the
+> synthesis flagged (addressing spectrum) and is the reason it earns a memo rather than
+> a footnote.
+
+Contrast set: Roam (block-DB, in-app), Obsidian (file, page-level), Notion (hosted DB),
+Joplin (SQLite-local, files-on-sync). Logseq = **block-graph, files-canonical,
+index-derived** — and now *also* migrating toward SQLite (§5), a live UC-43 case.
+
+---
+
+## 1. Core architecture — files canonical, DataScript derived
+
+- **Storage:** plain-text **Markdown or Org-mode files on disk** — `pages/<Page>.md` and
+  `journals/<date>.md` — fully usable even if the app disappears (local-first, open
+  source, ClojureScript).
+- **Index:** a **DataScript** in-memory graph database, **derived** from the files: an
+  `mldoc` parser turns Markdown into an AST, extracts references/properties, and
+  transforms it into **DataScript entities** with tree-position attributes. Files are the
+  source of truth; the graph DB is a rebuildable projection. (In current versions a **DB
+  Worker** manages **both DataScript and SQLite** connections — see §5.)
+- This is the **files-canonical / index-derived** architecture (Obsidian's MetadataCache,
+  Git's working tree) — but here the derived index is a *full Datalog-queryable graph*,
+  not just a metadata cache. Logseq is the strongest evidence that **a file-backed shard
+  can support rich structured queries via a derived index** (UC-52, UC-63).
+
+---
+
+## 2. The block-graph, in the file text
+
+Everything is an **atomic block** (a bullet), individually referenceable, embeddable, and
+queryable — Roam's model — but the addressing lives **in the Markdown**:
+
+- **Block IDs are in-file properties.** When a block is referenced, Logseq writes an
+  `id:: <uuid>` property line into the Markdown. So the block's stable address is
+  **git-diffable text that survives a file copy**, not a DB-minted hidden key. This is the
+  **sweet spot of the addressing spectrum**: block-level (like Roam) *and* in-file/
+  portable (like Obsidian's `^id`), without choosing.
+- **References:** `[[page]]`, **`((block-uuid))`**, `#tag` — all extracted into the graph;
+  block embeds `{{embed ((uuid))}}` are transclusion at block granularity (UC-32).
+- **Properties:** `key:: value` lines attach typed metadata to blocks (block properties)
+  and pages (first-block/page properties) — **git-diffable structured data at block
+  granularity** (UC-34), queried by Datalog.
+- **Outline tree:** a page is a **nested tree of blocks** (indent = structure), with
+  outliner operations — indent/outdent, move subtree, **zoom/narrow** into a block. The
+  page is not flat prose; it is an addressable, reorderable block tree (UC-63).
+
+---
+
+## 3. Queries — Datalog over the derived graph
+
+Logseq exposes **`{{query}}`** (simple) and **advanced Datalog queries** over the
+DataScript graph (and via the plugin API, `logseq.DB.datascriptQuery`). Because the graph
+is derived from files, **query-defined pages** (UC-54) and structured aggregation (tasks,
+tagged blocks) run over a *file-backed* store. Key lesson: query capability here is
+**neither native-DB (Notion) nor a third-party plugin (Obsidian Dataview)** — it is
+**built into the tool over its own files**, demonstrating that *a derived query index is a
+viable adapter/orchestrator capability for file shards* (UC-63).
+
+---
+
+## 4. Extension surface — plugin API + marketplace
+
+Logseq has a JS **plugin API** (marketplace ~486 plugins, `logseq/marketplace`):
+
+- `logseq.Editor` — block/page CRUD, insert/move/update/delete, get current block/page.
+- `logseq.DB` — **`datascriptQuery`** (Datalog), plus DB change subscriptions.
+- `logseq.App` — app-level ops/events; `logseq.UI`; `logseq.Git` (git ops on the graph);
+  `logseq.Assets`; `logseq.FileStorage`.
+- Slash commands, block/page context menus, `provideModel`/`provideStyle`, hooks/events.
+
+So, like Obsidian, Logseq is **dual-attachable**: (a) **file-store direct** — read the
+`pages/`+`journals/` Markdown with a **Logseq format profile** (parse `id::`, `((uuid))`,
+`key::`, the outline tree); (b) **in-app plugin host** — `logseq.Editor` write +
+`logseq.DB` query + change events for live write-through. A notable extra: a built-in
+**`logseq.Git`** surface — the tool treats git as a first-class companion to the file
+graph (validating the coordination journal).
+
+---
+
+## 5. The file→DB migration — a live UC-43
+
+Logseq is **migrating its storage model from Markdown-files to a SQLite "DB graph"**
+(the DB Worker already manages SQLite alongside DataScript; the plugin API has a distinct
+"DB graph" mode with tags/classes/typed properties). This is a real-world instance of
+**UC-43 (backend-swap under stable identity)**: the *same tool and graph identity* moving
+from a file substrate to a DB substrate, trading git-diffability for richer typed
+structure (toward the Notion/XWiki end). For shard-wiki it is both a caution (a shard's
+substrate can change under it) and a confirmation that the **addressing/structure/history
+spectra** are trajectories tools actually travel — an adapter keyed to a fixed substrate
+will break.
+
+---
+
+## 6. Logseq as a shard — capability profile
+
+| Capability | Logseq (MD-file graph) | Notes for the adapter contract |
+|------------|------------------------|--------------------------------|
+| Read | **yes** | file-store direct (pages/journals MD) or `logseq.Editor`/`logseq.DB` in-app |
+| Write | **yes** | direct file write (format-aware) or plugin; block-level |
+| Write granularity | **per-block** (in a per-file page) | finer than Obsidian (per-file), like Roam — but on files |
+| Identity / addressing | **in-file block `id:: uuid` + `((uuid))`** | block-level **and** git-diffable — the addressing sweet spot (UC-51) |
+| Structure | `key:: value` block/page properties; outline tree | git-diffable structured data at block granularity (UC-34) |
+| History | none native; **`logseq.Git`** + files = git-native | git-friendly out of the box (adopt, not supplement) |
+| Native query | **Datalog over derived DataScript** | derived index over files → delegate or rebuild (UC-52, UC-63) |
+| Transclusion | **block embeds `{{embed ((uuid))}}`** | in-file, addressable (UC-32) |
+| Backlinks | linked + unlinked references | derived (UC-05/18) |
+| Content types | Markdown/Org + **whiteboards** (tldraw JSON) | non-Markdown spatial content (UC-55) |
+| Substrate | **files now, SQLite "DB graph" emerging** | live backend-swap (UC-43) |
+| Attach modes | file-store direct (format profile) · in-app plugin | dual, per-binding (UC-62) |
+
+Verdict: **the most shard-wiki-friendly block tool** — block-graph power with file-over-
+app sovereignty and git-diffable addressing/structure. Best attach: **file-store direct
+with a Logseq format profile** (offline, git-native), with the plugin for live write-
+through. Watch the **DB-graph migration** (UC-43).
+
+---
+
+## 7. Mapping to shard-wiki INTENT (compare, do not equate)
+
+### 7.1 Reinforcements
+
+- **Resolves the addressing tension.** Block-level addressing *can* be git-diffable
+  in-file (`id::`), not forced to choose Roam-DB vs Obsidian-page (UC-51, synthesis §2).
+- **Confirms files-canonical / index-derived at full power** — a Datalog graph derived
+  from files, not just a metadata cache (UC-52, UC-63).
+- **Structure as git-diffable text** (`key::`) reinforces "prefer in-text structure"
+  (UC-34, synthesis through-line).
+- **Outliner block tree** validates the page-as-addressable-block-tree demand (UC-50,
+  UC-63) on a *file* backend.
+
+### 7.2 Deliberate divergences (design bugs if conflated)
+
+1. **One graph = one shard.** Local-first single graph; not the federation layer.
+2. **The MD files carry Logseq-specific syntax** (`id::`, `((uuid))`, `key::`, outline
+   semantics) — a **format profile**, not plain CommonMark. A naïve Markdown reader will
+   mangle block IDs/properties (cf. UC-42; lighter than Notion's lossy case).
+3. **The substrate is moving (file→SQLite).** Don't hard-code the file model; gate on the
+   substrate capability and tolerate the swap (UC-43).
+4. **Whiteboards are not Markdown** — typed/opaque assets, not flattened (UC-55).
+
+### 7.3 What Logseq teaches that shard-wiki should keep
+
+- **In-file block addressing is the target shape** for a portable span address where the
+  backend cooperates — adopt `id::`-style schemes; they are git-diffable and survive copy.
+- **A derived query index over files is a first-class capability** — shard-wiki can build
+  one over a file shard (UC-63) when the backend exposes none, or delegate when it does.
+- **Expect substrate migration** — bind to capabilities, not to "it's files."
+
+---
+
+## 8. Use-case seeds → catalog (promoted 2026-06-14)
+
+Last existing UC is **UC-61**. New UCs **UC-62, UC-63** added; existing UCs enriched.
+
+| Seed | Catalog action |
+|------|----------------|
+| **Attach a block-graph-on-plain-files shard** (Logseq-style): file-over-app Markdown carrying in-file block IDs (`id::`), block refs, and `key::` properties, with the outline tree and a derivable query index | **UC-62 (new)** |
+| **Serve structured queries over a file-backed shard via a derived index** the orchestrator/adapter builds (Logseq DataScript-over-files) when the backend exposes none | **UC-63 (new)** |
+| In-file block `id::` = block-level **and** git-diffable addressing (the spectrum sweet spot) | **enriches UC-51** |
+| Live **file→SQLite substrate migration** under stable graph identity | **enriches UC-43** |
+| Block-graph that is **files, not a DB** — the file-store variant of the block tool family | **enriches UC-50** |
+| Datalog over a **derived** index built from files | **enriches UC-52** |
+| `key:: value` block/page properties in-text | **enriches UC-34** |
+| Whiteboards (tldraw JSON) = non-Markdown content | **enriches UC-55** |
+| Block embeds `{{embed ((uuid))}}` = in-file transclusion | links UC-32 |
+
+---
+
+## 9. Architecture notes for SHARD-WP-0002 (no UC)
+
+- **Format-aware file-store profiles** (already flagged by Joplin, UC-60) gain a strong
+  case here: a Logseq profile parses `id::`/`((uuid))`/`key::`/outline from otherwise-
+  plain Markdown. The contract should let a file-store adapter declare its **format
+  profile** (plain MD / Obsidian / Logseq / Joplin-item / Foswiki-PlainFile). (T11/T14.)
+- **Derived-query-index as an orchestrator capability** (UC-63): when a file shard has no
+  native query engine, build a DataScript-like index over the projection; when it does
+  (Roam/Notion/XWiki), delegate (UC-52). Both belong in T16's navigation layer + T11.
+- **Substrate-migration tolerance** (UC-43, Logseq file→SQLite): T14 binding should treat
+  substrate as a capability that can change under a live attachment, preserving identity.
+- **In-file block addressing** is the concrete realization of T16's span-address thread —
+  prefer `id::`-style git-diffable IDs over DB-minted where the backend allows.
+
+---
+
+## 10. Open questions (for spec / workplans)
+
+1. When the same tool offers **file** and **DB** substrates (Logseq now), does shard-wiki
+   prefer the file graph (git-diffable, UC-62) or the DB graph (richer typed structure),
+   and can one binding follow the migration (UC-43)?
+2. Is the **derived query index** (UC-63) built by the **adapter** (per-shard) or the
+   **core orchestrator** (over the union), and is it persisted or rebuilt?
+3. How much **Logseq outline semantics** (zoom, subtree move) must shard-wiki preserve vs.
+   present as a flat page (UC-63 vs. Markdown-first page model)?
+4. Does the **Logseq format profile** round-trip overlays (write `id::`/`key::` back) or
+   only read them? (cf. UC-42 round-trip question.)
+
+---
+
+## 11. Sources
+
+| Source | Used for |
+|--------|----------|
+| DeepWiki — logseq/logseq (https://deepwiki.com/logseq/logseq) | DataScript+Datalog graph, mldoc AST parse, block entities/tree, DB Worker managing DataScript **and** SQLite |
+| logseq/docs (https://deepwiki.com/logseq/docs) | Plain-text MD/Org files; pages/journals; references ([[ ]], (( )), #tag); properties |
+| Logseq Plugin API docs (https://plugins-doc.logseq.com/) | `logseq.App/Editor/DB/Git/UI/Assets/FileStorage`; `DB.datascriptQuery` |
+| logseq/marketplace (https://github.com/logseq/marketplace) | Plugin distribution; ~486 plugins |
+| kerim/logseq-db-plugin-api-skill (https://github.com/kerim/logseq-db-plugin-api-skill) | DB-graph version: tags/classes, typed properties, file→DB migration |
+| pangea.app glossary — Logseq (https://pangea.app/glossary/logseq) | Local-first framing, outliner, plain-text control |
+
+Cross-references: `research/260614-roam-deep-dive/findings.md` (block-DB contrast),
+`research/260614-obsidian-deep-dive/findings.md` (file-over-app, derived index),
+`research/260614-joplin-deep-dive/findings.md` (format-aware file-store profiles),
+`research/260614-shard-spectrum-synthesis/findings.md` (addressing spectrum this
+resolves), `spec/UseCaseCatalog.md` (UC-32, UC-34, UC-43, UC-50, UC-51, UC-52, UC-55),
+`workplans/SHARD-WP-0002-federation-architecture.md` (T11, T14, T16).
+
+---
+
+## 12. Traceability
+
+- New UCs: **UC-62, UC-63** → `spec/UseCaseCatalog.md`.
+- Enriched UCs: **UC-32, UC-34, UC-43, UC-50, UC-51, UC-52, UC-55**.
+- Architecture (no UC): format-aware file-store profiles (Logseq profile); derived-query-
+  index capability; substrate-migration tolerance; in-file block addressing as the T16
+  span-address target → `SHARD-WP-0002` (T11, T14, T16).
+- Boundary recorded: Logseq is **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 (UC-43).
+</content>
--- a/research/README.md
+++ b/research/README.md
@@ -23,4 +23,5 @@ when multiple files or sources are involved. Findings here inform `spec/` and
 | 2026-06-14 | `260614-obsidian-deep-dive/` | Obsidian — file-over-app vaults, plugin API, ecosystem-popularity → UC signal; UC-53/54/55/56 |
 | 2026-06-14 | `260614-notion-deep-dive/` | Notion — closed block-DB SaaS, external REST API only, database-as-pages; UC-57/58/59 |
 | 2026-06-14 | `260614-shard-spectrum-synthesis/` | Synthesis — shard family matrix + eleven capability spectra across nine systems; feeds SHARD-WP-0002 T11–T16 |
-| 2026-06-14 | `260614-joplin-deep-dive/` | Joplin — SQLite-local/Markdown-on-sync, interchange-format attach, E2EE content opacity; UC-60/61 |
+| 2026-06-14 | `260614-joplin-deep-dive/` | Joplin — SQLite-local/Markdown-on-sync, interchange-format attach, E2EE content opacity; UC-60/61 |
+| 2026-06-14 | `260614-logseq-deep-dive/` | Logseq — block-graph on plain Markdown files, in-file block IDs, derived Datalog index; UC-62/63 |
--- a/spec/UseCaseCatalog.md
+++ b/spec/UseCaseCatalog.md
@@ -8,7 +8,8 @@ Promoted from `research/260608-c2-wiki-origins/`,
 `research/260613-twiki-deep-dive/`, `research/260613-foswiki-deep-dive/`,
 `research/260614-xanadu-deep-dive/`, `research/260614-zigzag-deep-dive/`,
 `research/260614-roam-deep-dive/`, `research/260614-obsidian-deep-dive/`,
-`research/260614-notion-deep-dive/`, and `research/260614-joplin-deep-dive/`.
+`research/260614-notion-deep-dive/`, `research/260614-joplin-deep-dive/`, and
+`research/260614-logseq-deep-dive/`.
 See InfoTechPrimers on coulomb.social for use-case catalog conventions.

 ## Conventions
@@ -201,7 +202,8 @@ UC-44 for the whole-page composition-manifest form. **Roam ships this**: block e
 transclude by `:block/uid` live (not copied), proving transclusion is a cheap data-layer
 capability over an addressable store (`research/260614-roam-deep-dive/findings.md` §3,
 §7) — argues for transclusion in core over the union, surfaced by UI. Depends on span
-addressing (UC-51).  
+addressing (UC-51). **Logseq** does the same on *files*: `{{embed ((uuid))}}` transcludes
+by an in-file block ID (`research/260614-logseq-deep-dive/findings.md` §2).  
 **Priority:** Later

 ### UC-33 — Git-branch an information space
@@ -238,7 +240,10 @@ sidecar metadata, and a candidate for query delegation (UC-52). Obsidian shows t
 and are queried by the Dataview plugin (`research/260614-obsidian-deep-dive/findings.md`
 §3) — structure as portable text, not DB state. **Notion** is the apex of the DB-locked
 end: typed database properties with relations/rollups/formulas, lossy to Markdown —
-see UC-58 (`research/260614-notion-deep-dive/findings.md` §2).  
+see UC-58 (`research/260614-notion-deep-dive/findings.md` §2). **Logseq** sits between:
+`key:: value` block/page properties live in the Markdown text (git-diffable) yet are
+queried via a derived Datalog graph (`research/260614-logseq-deep-dive/findings.md` §2–§3)
+— in-text structure at block granularity.  
 **Priority:** Later

 ### UC-35 — Attach a shard with coarse write granularity
@@ -406,7 +411,10 @@ versioned `Foswiki::Store` interface (`research/260613-foswiki-deep-dive/finding
 §2). shard-wiki orchestration robustness: a shard's identity/attachment is **not** its
 storage format. Open: detect the swap and preserve history across it (findings §9 Q3).
 Relates to UC-40 (attach path) and UC-41 (history import) but is about *change under a
-live attachment*, not initial attach.  
+live attachment*, not initial attach. Live modern instance: **Logseq** is migrating its
+substrate from Markdown-files to a SQLite "DB graph" under a stable graph identity
+(`research/260614-logseq-deep-dive/findings.md` §5) — bind to capabilities, not to "it's
+files".  
 **Priority:** Later

 ### UC-44 — Compose a page by reference (xanadoc / EDL manifest)
@@ -508,7 +516,9 @@ else degrade to read/projection/overlay-target (findings §11 Q2). **Notion** is
 external-API variant of the same block-DB family: a server Postgres store with a real
 **external** REST API, so write-through needs **no in-engine hosting** — but is bounded
 by rate limits and eventual consistency (UC-57,
-`research/260614-notion-deep-dive/findings.md` §4).  
+`research/260614-notion-deep-dive/findings.md` §4). **Logseq** is the *file-store* variant
+of the block-tool family — block-graph semantics over plain Markdown files, not a DB — see
+UC-62 (`research/260614-logseq-deep-dive/findings.md` §1–§2).  
 **Priority:** Later

 ### UC-51 — Adopt a shard's native span IDs as portable span addresses
@@ -531,7 +541,10 @@ UID. Notion is a second store-minted case: per-block **UUID v4**, exposed via th
 API (`research/260614-notion-deep-dive/findings.md` §1). **Joplin** marks the spectrum's
 middle: a store-minted **page-level** 32-char ID with `:/<id>` links that survive
 rename/move (`research/260614-joplin-deep-dive/findings.md` §1) — coarser than a block
-UUID, more stable than a path.  
+UUID, more stable than a path. **Logseq** is the **sweet spot**: a block-level `id:: uuid`
+stored **in the Markdown text** — fine-grained *and* git-diffable/portable at once,
+resolving the Roam(DB-minted) vs Obsidian(page-level) tension
+(`research/260614-logseq-deep-dive/findings.md` §2).  
 **Priority:** Later

 ### UC-52 — Delegate derived views to a shard's native query engine
@@ -549,7 +562,10 @@ nuance: query can be an *ecosystem plugin* (Dataview), **not core** — so "nati
 is adapter/plugin-provided and must not be assumed
 (`research/260614-obsidian-deep-dive/findings.md` §7). **Notion** ships a native
 database **query API** (filters/sorts) — a strong delegation target
-(`research/260614-notion-deep-dive/findings.md` §2, §4).  
+(`research/260614-notion-deep-dive/findings.md` §2, §4). **Logseq** shows the third path:
+Datalog over a **derived** index built from plain files — neither native-DB nor plugin;
+when no engine exists, shard-wiki can build the index itself (UC-63,
+`research/260614-logseq-deep-dive/findings.md` §3).  
 **Priority:** Later

 ### UC-53 — Attach a local-first Markdown vault with a live concurrent native editor
@@ -598,7 +614,8 @@ Pushes the **wiki page model**: page vs. typed asset vs. opaque blob — a page-
 decision, not just adapter config (findings §10). JSON Canvas is an open format worth
 first-class support. **Joplin** resources (attachments, each with an ID, linked `:/<id>`)
 are the same demand in a sync-mirror shard (`research/260614-joplin-deep-dive/findings.md`
-§5).  
+§5). **Logseq whiteboards** (tldraw JSON) are the same in a file-store block shard
+(`research/260614-logseq-deep-dive/findings.md` §6).  
 **Priority:** Later

 ### UC-56 — Publish a curated projection to an external read-only target
@@ -704,6 +721,40 @@ undecryptable content. Open: does shard-wiki ever hold keys, or only treat such
 opaque backups (findings §9 Q1)? Ties [[shard-wiki-auth-in-core-decision]].  
 **Priority:** Later

+### UC-62 — Attach a block-graph-on-plain-files shard
+
+**Actor:** Maintainer  
+**Goal:** Attach a Logseq-style local outliner — block-graph semantics stored as plain
+Markdown/Org files — preserving its in-file block IDs, block/page properties, and outline
+tree, with a derivable query index.  
+**Source:** logseq, intent  
+**Notes:** Logseq is **file-over-app *and* block-graph**: blocks carry an in-file
+`id:: <uuid>` property, `((uuid))` refs, and `key:: value` properties, with a DataScript
+graph **derived** from the files (`research/260614-logseq-deep-dive/findings.md` §1–§2).
+The addressing **sweet spot** — block-level *and* git-diffable (UC-51) — resolving the
+Roam(DB-minted)/Obsidian(page-level) tension. Attach **file-store direct with a Logseq
+format profile** (parse `id::`/`((uuid))`/`key::`/outline) or via the in-app plugin
+(`logseq.Editor`/`logseq.DB`). Distinct from UC-50 (Roam: block-DB, not files) and UC-53
+(Obsidian: page-level, path-addressed). Watch the file→SQLite substrate migration
+(UC-43).  
+**Priority:** Later
+
+### UC-63 — Serve structured queries over a file-backed shard via a derived index
+
+**Actor:** Reader or orchestrator  
+**Goal:** Run structured queries (tasks, tagged blocks, typed properties) over a
+file-backed shard that exposes no native query engine, using an index the orchestrator or
+adapter builds and rebuilds from the files.  
+**Source:** logseq, intent  
+**Notes:** Logseq proves a **file-backed** store supports rich **Datalog** queries via a
+**derived DataScript index** (files canonical, graph derived —
+`research/260614-logseq-deep-dive/findings.md` §1, §3). The converse of UC-52 (delegate to
+a *native* engine): here shard-wiki **builds** the index over the projection when none
+exists. Operationalizes the ZigZag dimensions / Roam-Notion query model on a file shard.
+Open: built by adapter (per-shard) or core (over the union); persisted vs rebuilt
+(findings §10 Q2). Belongs to the T16 navigation layer + T11 capabilities.  
+**Priority:** Later
+
 ---

 ## B. Knowledge work and collaboration
@@ -953,6 +1004,8 @@ CamelCase and `[[free links]]`. Markdown-first link semantics TBD.
 | UC-59 | | | | ◊ | ✓ |
 | UC-60 | | | | ‖ | ✓ |
 | UC-61 | | | | ‖ | ✓ |
+| UC-62 | | | | ※ | ✓ |
+| UC-63 | | | | ※ | ✓ |
 | UC-08 | ✓ | | |
 | UC-09 | ✓ | | |
 | UC-10 | ✓ | | |
@@ -1235,6 +1288,35 @@ never re-syncs, and treats the DB-local store and encrypted content as opaque
 `SHARD-WP-0002` (T11/T14): interchange-format attach, content-opacity field, local-REST
 sub-mode, format-aware file-store profiles.

+### logseq mapping
+
+(※ UC-62–UC-63 are placed in the **wikiengines** matrix column as the nearest existing
+source — Logseq is a shipped tool — but their true lineage is the **Logseq deep dive**,
+`research/260614-logseq-deep-dive/findings.md`.)
+
+| Logseq mechanism (findings §) | Catalog UC |
+|-------------------------------|------------|
+| Block-graph semantics on plain MD/Org files; in-file `id::`/`((uuid))`/`key::` (§1–§2) | UC-62 (new) |
+| Datalog over a **derived** DataScript index built from files (§1, §3) | UC-63 (new) |
+| In-file block `id::` = block-level **and** git-diffable addressing (the sweet spot) (§2) | UC-51 (enriched) |
+| File→SQLite "DB graph" substrate migration under stable identity (§5) | UC-43 (enriched) |
+| Block-graph that is **files, not a DB** — file-store variant of the block-tool family (§1) | UC-50 (enriched) |
+| Datalog over a derived index (third path: not native-DB, not plugin) (§3) | UC-52 (enriched) |
+| `key:: value` block/page properties in-text (§2) | UC-34 (enriched) |
+| Whiteboards (tldraw JSON) = non-Markdown content (§6) | UC-55 (enriched) |
+| Block embeds `{{embed ((uuid))}}` = in-file transclusion (§2) | links UC-32 |
+
+Note: Logseq is the **block-graph-on-plain-files** point the other modern tools leave
+empty — the bridge between Roam (block-DB) and Obsidian (file-over-app) — and it
+**resolves the addressing-spectrum tension**: block-level addressing that is also
+git-diffable in-file text (`id::`). It confirms a **file-backed shard can serve rich
+Datalog queries via a derived index** (files canonical, graph derived). **Boundary
+recorded:** one block-graph-on-files candidate shard (the addressing sweet spot), best
+attached file-store-direct with a Logseq **format profile**; not the federation layer;
+substrate migrating file→SQLite (UC-43). Architecture logged for `SHARD-WP-0002`
+(T11/T14/T16): Logseq format profile, derived-query-index capability, substrate-migration
+tolerance, in-file block addressing as the concrete T16 span-address target.
+
 ---

 ## Open questions
@@ -1268,4 +1350,9 @@ sub-mode, format-aware file-store profiles.
 14. For an **encrypted shard** (UC-61), what is visible without keys (IDs/structure vs
    nothing), and does shard-wiki ever hold keys or only treat it as an opaque backup?
 15. Is writing to a tool's **sync mirror** (UC-60) ever safe, or are interchange-format
-    shards read/projection/overlay-only by policy? (Joplin dive §9.)
+    shards read/projection/overlay-only by policy? (Joplin dive §9.)
+16. Is the **derived query index** (UC-63) built by the adapter (per-shard) or the core
+    orchestrator (over the union), and is it persisted or rebuilt? (Logseq dive §10.)
+17. When a tool offers **both file and DB substrates** (Logseq), does shard-wiki prefer
+    the git-diffable file graph or the richer DB graph, and can one binding follow the
+    migration? (UC-43, UC-62.)