diff --git a/SCOPE.md b/SCOPE.md index 2dff729..bb73d7c 100644 --- 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) diff --git a/research/260614-logseq-deep-dive/README.md b/research/260614-logseq-deep-dive/README.md new file mode 100644 index 0000000..b1d5db5 --- /dev/null +++ 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:: ` 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. + diff --git a/research/260614-logseq-deep-dive/findings.md b/research/260614-logseq-deep-dive/findings.md new file mode 100644 index 0000000..ae8a694 --- /dev/null +++ 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/.md` and + `journals/.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:: ` 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). + diff --git a/research/README.md b/research/README.md index fbfab31..bb0fdda 100644 --- 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 | \ No newline at end of file +| 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 | \ No newline at end of file diff --git a/spec/UseCaseCatalog.md b/spec/UseCaseCatalog.md index 6e47425..f34ebf0 100644 --- 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 `:/` 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 `:/`) 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:: ` 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.) \ No newline at end of file + 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.) \ No newline at end of file