@geml/logseq-sync 2.0.9 → 2.2.0

package/docs/how-it-works.svg

@@ -1,42 +1,42 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 250" font-family="ui-sans-serif,system-ui,Segoe UI,Helvetica,Arial,sans-serif">
-  <defs>
-    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/>
-    </marker>
-  </defs>
-  <rect x="0" y="0" width="760" height="250" rx="12" fill="#f6f8fa" stroke="#d0d7de"/>
-
-  <!-- Logseq app box -->
-  <rect x="24" y="36" width="220" height="130" rx="10" fill="#ffffff" stroke="#a475f9" stroke-width="1.5"/>
-  <text x="134" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">Logseq 2.0 (DB graph)</text>
-  <rect x="44" y="80" width="180" height="66" rx="8" fill="#f3ecff" stroke="#a475f9"/>
-  <text x="134" y="104" text-anchor="middle" font-size="13" font-weight="600" fill="#3b2a63">Sync Vault with GEML plugin</text>
-  <text x="134" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">DB.onChanged → debounce</text>
-  <text x="134" y="139" text-anchor="middle" font-size="11.5" fill="#57606a">status in toolbar ⇄</text>
-
-  <!-- signal file -->
-  <rect x="286" y="70" width="160" height="42" rx="8" fill="#fff8c5" stroke="#d4a72c"/>
-  <text x="366" y="88" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">dirty-marker file</text>
-  <text x="366" y="103" text-anchor="middle" font-size="10.5" fill="#7d8590">…/storages/logseq-plugin-sync-vault-with-geml/</text>
-
-  <!-- status file -->
-  <rect x="286" y="128" width="160" height="34" rx="8" fill="#ddf4ff" stroke="#54aeff"/>
-  <text x="366" y="149" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">geml-sync-status.json</text>
-
-  <!-- watcher box -->
-  <rect x="488" y="36" width="248" height="130" rx="10" fill="#ffffff" stroke="#2da44e" stroke-width="1.5"/>
-  <text x="612" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">logseq-sync watcher (CLI)</text>
-  <text x="612" y="86" text-anchor="middle" font-size="11.5" fill="#57606a">export via official @logseq/cli</text>
-  <text x="612" y="103" text-anchor="middle" font-size="11.5" fill="#57606a">writes only files that changed</text>
-  <text x="612" y="120" text-anchor="middle" font-size="11.5" fill="#57606a">git commit scoped to the vault</text>
-  <text x="612" y="145" text-anchor="middle" font-size="11.5" font-weight="600" fill="#2da44e">your-vault/pages/*.geml · git</text>
-
-  <!-- arrows -->
-  <line x1="244" y1="91" x2="284" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-  <line x1="446" y1="91" x2="486" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-  <line x1="486" y1="145" x2="446" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-  <line x1="286" y1="145" x2="246" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-
-  <text x="380" y="196" text-anchor="middle" font-size="12.5" fill="#57606a">The plugin is a doorbell, not the mover: the sandbox has no filesystem and no git,</text>
-  <text x="380" y="214" text-anchor="middle" font-size="12.5" fill="#57606a">so everything with side effects lives in the watcher — auditable, scoped, outside the app.</text>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 250" font-family="ui-sans-serif,system-ui,Segoe UI,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/>
+    </marker>
+  </defs>
+  <rect x="0" y="0" width="760" height="250" rx="12" fill="#f6f8fa" stroke="#d0d7de"/>
+
+  <!-- Logseq app box -->
+  <rect x="24" y="36" width="220" height="130" rx="10" fill="#ffffff" stroke="#a475f9" stroke-width="1.5"/>
+  <text x="134" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">Logseq 2.0 (DB graph)</text>
+  <rect x="44" y="80" width="180" height="66" rx="8" fill="#f3ecff" stroke="#a475f9"/>
+  <text x="134" y="104" text-anchor="middle" font-size="13" font-weight="600" fill="#3b2a63">Sync Vault with GEML plugin</text>
+  <text x="134" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">DB.onChanged → debounce</text>
+  <text x="134" y="139" text-anchor="middle" font-size="11.5" fill="#57606a">status in toolbar ⇄</text>
+
+  <!-- signal file -->
+  <rect x="286" y="70" width="160" height="42" rx="8" fill="#fff8c5" stroke="#d4a72c"/>
+  <text x="366" y="88" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">dirty-marker file</text>
+  <text x="366" y="103" text-anchor="middle" font-size="10.5" fill="#7d8590">…/storages/logseq-plugin-sync-vault-with-geml/</text>
+
+  <!-- status file -->
+  <rect x="286" y="128" width="160" height="34" rx="8" fill="#ddf4ff" stroke="#54aeff"/>
+  <text x="366" y="149" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">geml-sync-status.json</text>
+
+  <!-- watcher box -->
+  <rect x="488" y="36" width="248" height="130" rx="10" fill="#ffffff" stroke="#2da44e" stroke-width="1.5"/>
+  <text x="612" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">logseq-sync watcher (CLI)</text>
+  <text x="612" y="86" text-anchor="middle" font-size="11.5" fill="#57606a">export via official @logseq/cli</text>
+  <text x="612" y="103" text-anchor="middle" font-size="11.5" fill="#57606a">writes only files that changed</text>
+  <text x="612" y="120" text-anchor="middle" font-size="11.5" fill="#57606a">git commit scoped to the vault</text>
+  <text x="612" y="145" text-anchor="middle" font-size="11.5" font-weight="600" fill="#2da44e">your-vault/pages/*.geml · git</text>
+
+  <!-- arrows -->
+  <line x1="244" y1="91" x2="284" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+  <line x1="446" y1="91" x2="486" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+  <line x1="486" y1="145" x2="446" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+  <line x1="286" y1="145" x2="246" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+
+  <text x="380" y="196" text-anchor="middle" font-size="12.5" fill="#57606a">The plugin is a doorbell, not the mover: the sandbox has no filesystem and no git,</text>
+  <text x="380" y="214" text-anchor="middle" font-size="12.5" fill="#57606a">so everything with side effects lives in the watcher — auditable, scoped, outside the app.</text>
+</svg>

package/package.json

@@ -1,58 +1,58 @@
-{
-  "name": "@geml/logseq-sync",
-  "version": "2.0.9",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "Continuously sync a Logseq DB graph to a Git-friendly folder of readable plain-text GEML files — the watcher half of the Sync Vault with GEML plugin. Built on the official @logseq/cli export; writes only files that changed, commits scoped strictly to the vault.",
-  "type": "module",
-  "bin": {
-    "logseq-sync": "watcher/bin/logseq-sync.mjs"
-  },
-  "files": [
-    "core/src",
-    "watcher/bin",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "logseq",
-    "logseq-plugin",
-    "sync",
-    "git",
-    "plain-text",
-    "geml",
-    "vault",
-    "backup"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/geml-spec/geml.git",
-    "directory": "integrations/logseq"
-  },
-  "homepage": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml#readme",
-  "bugs": {
-    "url": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml/issues"
-  },
-  "license": "MIT",
-  "workspaces": [
-    "plugin"
-  ],
-  "scripts": {
-    "test": "node core/test/roundtrip.test.mjs && node core/test/sync.test.mjs && node core/test/discovery.test.mjs && node watcher/test/cli-sync.test.mjs && node watcher/test/signal-sync.test.mjs && node watcher/test/zero-config.test.mjs && node plugin/test/core.test.mjs",
-    "sync": "node watcher/bin/logseq-sync.mjs",
-    "build:plugin": "node plugin/build.mjs"
-  },
-  "dependencies": {
-    "@geml/geml": "^1.8.8",
-    "edn-data": "^1.2.2"
-  },
-  "overrides": {
-    "dompurify": "^3.4.14",
-    "lodash-es": "^4.18.1"
-  }
-}
+{
+  "name": "@geml/logseq-sync",
+  "version": "2.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Continuously sync a Logseq DB graph to a Git-friendly folder of readable plain-text GEML files — the watcher half of the Sync Vault with GEML plugin. Built on the official @logseq/cli export; writes only files that changed, commits scoped strictly to the vault.",
+  "type": "module",
+  "bin": {
+    "logseq-sync": "watcher/bin/logseq-sync.mjs"
+  },
+  "files": [
+    "core/src",
+    "watcher/bin",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "logseq",
+    "logseq-plugin",
+    "sync",
+    "git",
+    "plain-text",
+    "geml",
+    "vault",
+    "backup"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geml-spec/geml.git",
+    "directory": "integrations/logseq"
+  },
+  "homepage": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml#readme",
+  "bugs": {
+    "url": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml/issues"
+  },
+  "license": "MIT",
+  "workspaces": [
+    "plugin"
+  ],
+  "scripts": {
+    "test": "node core/test/roundtrip.test.mjs && node core/test/sync.test.mjs && node core/test/discovery.test.mjs && node watcher/test/cli-sync.test.mjs && node watcher/test/signal-sync.test.mjs && node watcher/test/zero-config.test.mjs && node plugin/test/core.test.mjs",
+    "sync": "node watcher/bin/logseq-sync.mjs",
+    "build:plugin": "node plugin/build.mjs"
+  },
+  "dependencies": {
+    "@geml/geml": "^1.8.8",
+    "edn-data": "^1.2.2"
+  },
+  "overrides": {
+    "dompurify": "^3.4.14",
+    "lodash-es": "^4.18.1"
+  }
+}

package/watcher/bin/create-graph.mjs

@@ -1,51 +1,51 @@
-// Create an empty Logseq DB graph WITHOUT the desktop app.
-//
-//   LOGSEQ_CLI_DIR=<dir whose node_modules holds @logseq/cli>  \
-//   node bin/create-graph.mjs <graph-name>   (name travels via GEML_GRAPH_NAME —
-//   nbb loadFile does not surface *command-line-args*)
-//
-// Why this exists: `@logseq/cli` (0.4.3) can export, import and validate a DB
-// graph, but cannot create one — creation lives in the desktop app, and on a
-// machine where the app cannot run (permissions, CI) that is a dead end. The
-// CLI package VENDORS the whole logseq.db stack though, and its `open-db!`
-// creates the sqlite tables on open; the only other thing the app does at
-// create time is transact `build-db-initial-data`. So this does exactly those
-// two steps, through the CLI's own vendored code — the resulting graph is one
-// `logseq list/show/validate` accepts as its own (verified: schema 65.22,
-// "Valid!").
-import { fileURLToPath, pathToFileURL } from "url";
-import { dirname, resolve } from "path";
-import { existsSync, readFileSync, copyFileSync, rmSync } from "fs";
-
-const here = fileURLToPath(dirname(import.meta.url));
-const cliDir = process.env.LOGSEQ_CLI_DIR ?? resolve(here, "..");
-const CLI = resolve(cliDir, "node_modules", "@logseq", "cli");
-if (!existsSync(CLI)) {
-  console.error(`@logseq/cli not found under ${cliDir}/node_modules — set LOGSEQ_CLI_DIR to a directory where it is installed.`);
-  console.error("Note: on Node 24 its better-sqlite3 needs an override to >=12.11.1 for a prebuilt binding.");
-  process.exit(2);
-}
-
-// nbb-logseq is resolved from the CLI's install, not from this package: ESM
-// import specifiers resolve relative to THIS file, which would demand a local
-// install of a runtime the CLI already carries.
-const nbbDir = resolve(cliDir, "node_modules", "@logseq", "nbb-logseq");
-const nbbPkg = JSON.parse(readFileSync(resolve(nbbDir, "package.json"), "utf8"));
-const entry = typeof nbbPkg.exports === "object"
-  ? (nbbPkg.exports["."]?.import ?? nbbPkg.exports["."]) : (nbbPkg.main ?? "index.mjs");
-const { loadFile, addClassPath } = await import(pathToFileURL(resolve(nbbDir, entry)).href);
-
-global.__dirname = here;
-addClassPath(resolve(CLI, "src"));
-addClassPath(resolve(CLI, "vendor/src"));
-// nbb resolves the stack's node `require`s (better-sqlite3) relative to the
-// LOADED FILE's directory, so the .cljs must sit beside a node_modules that
-// has them — copy it into the CLI dir for the duration of the run.
-process.env.GEML_GRAPH_NAME = process.argv[2] ?? "geml-spike";
-const staged = resolve(cliDir, ".geml-create-graph.cljs");
-copyFileSync(resolve(here, "create_graph_headless.cljs"), staged);
-try {
-  await loadFile(staged);
-} finally {
-  rmSync(staged, { force: true });
-}
+// Create an empty Logseq DB graph WITHOUT the desktop app.
+//
+//   LOGSEQ_CLI_DIR=<dir whose node_modules holds @logseq/cli>  \
+//   node bin/create-graph.mjs <graph-name>   (name travels via GEML_GRAPH_NAME —
+//   nbb loadFile does not surface *command-line-args*)
+//
+// Why this exists: `@logseq/cli` (0.4.3) can export, import and validate a DB
+// graph, but cannot create one — creation lives in the desktop app, and on a
+// machine where the app cannot run (permissions, CI) that is a dead end. The
+// CLI package VENDORS the whole logseq.db stack though, and its `open-db!`
+// creates the sqlite tables on open; the only other thing the app does at
+// create time is transact `build-db-initial-data`. So this does exactly those
+// two steps, through the CLI's own vendored code — the resulting graph is one
+// `logseq list/show/validate` accepts as its own (verified: schema 65.22,
+// "Valid!").
+import { fileURLToPath, pathToFileURL } from "url";
+import { dirname, resolve } from "path";
+import { existsSync, readFileSync, copyFileSync, rmSync } from "fs";
+
+const here = fileURLToPath(dirname(import.meta.url));
+const cliDir = process.env.LOGSEQ_CLI_DIR ?? resolve(here, "..");
+const CLI = resolve(cliDir, "node_modules", "@logseq", "cli");
+if (!existsSync(CLI)) {
+  console.error(`@logseq/cli not found under ${cliDir}/node_modules — set LOGSEQ_CLI_DIR to a directory where it is installed.`);
+  console.error("Note: on Node 24 its better-sqlite3 needs an override to >=12.11.1 for a prebuilt binding.");
+  process.exit(2);
+}
+
+// nbb-logseq is resolved from the CLI's install, not from this package: ESM
+// import specifiers resolve relative to THIS file, which would demand a local
+// install of a runtime the CLI already carries.
+const nbbDir = resolve(cliDir, "node_modules", "@logseq", "nbb-logseq");
+const nbbPkg = JSON.parse(readFileSync(resolve(nbbDir, "package.json"), "utf8"));
+const entry = typeof nbbPkg.exports === "object"
+  ? (nbbPkg.exports["."]?.import ?? nbbPkg.exports["."]) : (nbbPkg.main ?? "index.mjs");
+const { loadFile, addClassPath } = await import(pathToFileURL(resolve(nbbDir, entry)).href);
+
+global.__dirname = here;
+addClassPath(resolve(CLI, "src"));
+addClassPath(resolve(CLI, "vendor/src"));
+// nbb resolves the stack's node `require`s (better-sqlite3) relative to the
+// LOADED FILE's directory, so the .cljs must sit beside a node_modules that
+// has them — copy it into the CLI dir for the duration of the run.
+process.env.GEML_GRAPH_NAME = process.argv[2] ?? "geml-spike";
+const staged = resolve(cliDir, ".geml-create-graph.cljs");
+copyFileSync(resolve(here, "create_graph_headless.cljs"), staged);
+try {
+  await loadFile(staged);
+} finally {
+  rmSync(staged, { force: true });
+}

package/watcher/bin/create_graph_headless.cljs

@@ -1,22 +1,22 @@
-(ns create-graph-headless
-  "Create an empty Logseq DB graph without the desktop app: the CLI package
-   vendors the whole logseq.db stack, and open-db! creates tables on open.
-   This does exactly what the app's create-graph does at the db level:
-   mkdir + open + transact build-db-initial-data.
-
-   open-db! creates the DATABASE but refuses a missing DIRECTORY (its error
-   says only 'Cannot open database because the directory does not exist'),
-   so the mkdir here is load-bearing."
-  (:require [logseq.db.common.sqlite-cli :as sqlite-cli]
-            [logseq.db.sqlite.create-graph :as sqlite-create-graph]
-            [datascript.core :as d]
-            ["fs" :as fs]
-            ["os" :as os]
-            ["path" :as node-path]))
-
-(def graph-name (or (aget (.-env js/process) "GEML_GRAPH_NAME") "geml-spike"))
-(def graphs-dir (node-path/join (os/homedir) "logseq" "graphs"))
-(fs/mkdirSync (node-path/join graphs-dir graph-name) #js {:recursive true})
-(def conn (sqlite-cli/open-db! graphs-dir graph-name))
-(d/transact! conn (sqlite-create-graph/build-db-initial-data "{}"))
-(println "created" (node-path/join graphs-dir graph-name))
+(ns create-graph-headless
+  "Create an empty Logseq DB graph without the desktop app: the CLI package
+   vendors the whole logseq.db stack, and open-db! creates tables on open.
+   This does exactly what the app's create-graph does at the db level:
+   mkdir + open + transact build-db-initial-data.
+
+   open-db! creates the DATABASE but refuses a missing DIRECTORY (its error
+   says only 'Cannot open database because the directory does not exist'),
+   so the mkdir here is load-bearing."
+  (:require [logseq.db.common.sqlite-cli :as sqlite-cli]
+            [logseq.db.sqlite.create-graph :as sqlite-create-graph]
+            [datascript.core :as d]
+            ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]))
+
+(def graph-name (or (aget (.-env js/process) "GEML_GRAPH_NAME") "geml-spike"))
+(def graphs-dir (node-path/join (os/homedir) "logseq" "graphs"))
+(fs/mkdirSync (node-path/join graphs-dir graph-name) #js {:recursive true})
+(def conn (sqlite-cli/open-db! graphs-dir graph-name))
+(d/transact! conn (sqlite-create-graph/build-db-initial-data "{}"))
+(println "created" (node-path/join graphs-dir graph-name))

package/watcher/bin/live-roundtrip.mjs

@@ -1,131 +1,131 @@
-// The live half of the spike: run the round trip against a REAL DB graph via
-// the official @logseq/cli, with Logseq's own `validate` as the judge.
-//
-//   node bin/live-roundtrip.mjs <graph-name> [--edit]
-//
-// Stages (each printed, each gated):
-//   1. `logseq export-edn -g <graph>`            → out/export-1.edn
-//   2. ednToGemlFiles                            → out/geml/**.geml
-//   3. `geml check --root out/geml` on every doc (zero errors required)
-//   4. gemlFilesToEdn                            → out/import.edn
-//   5. STRUCTURAL identity export-1 ⇄ import.edn (EDN semantics) — the offline
-//      criterion, now on real data
-//   6. with --edit: `geml set` the first uuid block, rebuild import.edn, and
-//      `logseq import-edn` it back, then `logseq validate` — the semantics
-//      probe: does re-import by uuid update in place, or append?
-//
-// Import-back is opt-in (--edit) because import semantics on a whole-graph
-// re-import are exactly what this stage exists to LEARN — it may merge, it may
-// duplicate id-less blocks. The script never touches a graph unless told to.
-import { execFileSync } from "node:child_process";
-import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseEDNString } from "edn-data";
-import { ednToGemlFiles, gemlFilesToEdn } from "../../core/src/mapping.mjs";
-import { parse, addressedUnits, sliceUnit } from "../../../../geml-parser/dist/geml.js";
-
-const here = dirname(fileURLToPath(import.meta.url));
-const out = join(here, "..", "out");
-const GEML = resolve(here, "..", "..", "..", "geml-parser", "dist", "geml.js");
-const lib = { parse, addressedUnits, sliceUnit };
-
-const [graph, ...flags] = process.argv.slice(2);
-if (!graph) { console.error("usage: node bin/live-roundtrip.mjs <graph-name> [--edit]"); process.exit(2); }
-const doEdit = flags.includes("--edit");
-
-// The CLI is driven through npx so nothing here depends on a global install;
-// LOGSEQ_CLI_DIR points at a directory whose node_modules has @logseq/cli.
-const cliCwd = process.env.LOGSEQ_CLI_DIR ?? join(here, "..");
-const logseq = (...args) =>
-  execFileSync("npx", ["-y", "@logseq/cli", ...args], { cwd: cliCwd, encoding: "utf8", shell: true, maxBuffer: 1 << 28 });
-const geml = (...args) =>
-  execFileSync(process.execPath, [GEML, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
-
-// EDN-semantics canonical form (same as the test suite).
-function canon(v) {
-  if (Array.isArray(v)) return v.map(canon);
-  if (v !== null && typeof v === "object") {
-    if (Array.isArray(v.map)) {
-      const entries = v.map.map(([k, val]) => [canon(k), canon(val)]);
-      entries.sort((a, b) => (JSON.stringify(a[0]) < JSON.stringify(b[0]) ? -1 : 1));
-      return { map: entries };
-    }
-    if (Array.isArray(v.set)) {
-      const items = v.set.map(canon);
-      items.sort((a, b) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1));
-      return { set: items };
-    }
-    const o = {};
-    for (const k of Object.keys(v).sort()) o[k] = canon(v[k]);
-    return o;
-  }
-  return v;
-}
-const same = (a, b) => JSON.stringify(canon(parseEDNString(a))) === JSON.stringify(canon(parseEDNString(b)));
-
-rmSync(out, { recursive: true, force: true });
-mkdirSync(join(out, "geml"), { recursive: true });
-
-console.log(`1. export-edn from graph "${graph}"`);
-logseq("export-edn", "-g", graph, "-f", join(out, "export-1.edn"));
-const edn1 = readFileSync(join(out, "export-1.edn"), "utf8");
-console.log(`   ${edn1.length} bytes of EDN`);
-
-console.log("2. EDN -> GEML");
-const files = ednToGemlFiles(edn1);
-for (const [rel, text] of files) {
-  mkdirSync(dirname(join(out, "geml", rel)), { recursive: true });
-  writeFileSync(join(out, "geml", rel), text);
-}
-console.log(`   ${files.size} documents`);
-
-console.log("3. geml check on every document");
-let dirty = 0;
-for (const rel of files.keys()) {
-  try { geml("check", "--root", join(out, "geml"), join(out, "geml", rel)); }
-  catch (e) { dirty++; console.error(`   FAIL ${rel}\n${e.stdout ?? ""}${e.stderr ?? ""}`); }
-}
-if (dirty) { console.error(`   ${dirty} document(s) not clean — stopping`); process.exit(1); }
-console.log("   all clean");
-
-console.log("4. GEML -> EDN");
-const files2 = new Map();
-for (const rel of files.keys()) files2.set(rel, readFileSync(join(out, "geml", rel), "utf8"));
-const edn2 = gemlFilesToEdn(files2, lib);
-writeFileSync(join(out, "import.edn"), edn2);
-
-console.log("5. structural identity, on the real graph");
-if (!same(edn1, edn2)) { console.error("   NOT identical — diff out/export-1.edn against out/import.edn"); process.exit(1); }
-console.log("   identical (EDN semantics)");
-
-if (!doEdit) { console.log("\nround trip holds. Re-run with --edit to probe import-back semantics."); process.exit(0); }
-
-console.log("6. edit one uuid block via `geml set`, import back, validate");
-const withUuid = [...files.keys()].map((rel) => {
-  const text = files2.get(rel);
-  const unit = [...addressedUnits(text)].map((a) => a.unit).find((u) => u.kind === "block" && u.id && /^[0-9a-f-]{36}$/.test(u.id));
-  return unit ? { rel, unit } : null;
-}).find(Boolean);
-if (!withUuid) { console.log("   no uuid-bearing block in this graph (nothing referenced) — skipping the edit probe"); process.exit(0); }
-
-const target = join(out, "geml", withUuid.rel);
-// Keep the block's own head line (type, id, level) — the edit is to the BODY.
-const src = files2.get(withUuid.rel);
-const head = sliceUnit(src, withUuid.unit.span, "head").trimEnd();
-const body = sliceUnit(src, withUuid.unit.span, "body").trimEnd();
-const fence = head.match(/^=+/)[0];
-writeFileSync(join(out, "edit.txt"), `${head}\n${body} — edited by geml\n${fence}\n`);
-geml("set", target, `#${withUuid.unit.id}`, "--in", join(out, "edit.txt"), "--root", join(out, "geml"));
-console.log(`   edited #${withUuid.unit.id} in ${withUuid.rel}`);
-
-const files3 = new Map();
-for (const rel of files.keys()) files3.set(rel, readFileSync(join(out, "geml", rel), "utf8"));
-writeFileSync(join(out, "import-edited.edn"), gemlFilesToEdn(files3, lib));
-logseq("import-edn", "-g", graph, "-f", join(out, "import-edited.edn"));
-console.log("   imported");
-console.log(logseq("validate", "-g", graph).trim());
-
-console.log("7. export again — inspect out/export-2.edn to judge merge semantics");
-logseq("export-edn", "-g", graph, "-f", join(out, "export-2.edn"));
-console.log("done — compare out/export-1.edn / out/export-2.edn");
+// The live half of the spike: run the round trip against a REAL DB graph via
+// the official @logseq/cli, with Logseq's own `validate` as the judge.
+//
+//   node bin/live-roundtrip.mjs <graph-name> [--edit]
+//
+// Stages (each printed, each gated):
+//   1. `logseq export-edn -g <graph>`            → out/export-1.edn
+//   2. ednToGemlFiles                            → out/geml/**.geml
+//   3. `geml check --root out/geml` on every doc (zero errors required)
+//   4. gemlFilesToEdn                            → out/import.edn
+//   5. STRUCTURAL identity export-1 ⇄ import.edn (EDN semantics) — the offline
+//      criterion, now on real data
+//   6. with --edit: `geml set` the first uuid block, rebuild import.edn, and
+//      `logseq import-edn` it back, then `logseq validate` — the semantics
+//      probe: does re-import by uuid update in place, or append?
+//
+// Import-back is opt-in (--edit) because import semantics on a whole-graph
+// re-import are exactly what this stage exists to LEARN — it may merge, it may
+// duplicate id-less blocks. The script never touches a graph unless told to.
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseEDNString } from "edn-data";
+import { ednToGemlFiles, gemlFilesToEdn } from "../../core/src/mapping.mjs";
+import { parse, addressedUnits, sliceUnit } from "../../../../geml-parser/dist/geml.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const out = join(here, "..", "out");
+const GEML = resolve(here, "..", "..", "..", "geml-parser", "dist", "geml.js");
+const lib = { parse, addressedUnits, sliceUnit };
+
+const [graph, ...flags] = process.argv.slice(2);
+if (!graph) { console.error("usage: node bin/live-roundtrip.mjs <graph-name> [--edit]"); process.exit(2); }
+const doEdit = flags.includes("--edit");
+
+// The CLI is driven through npx so nothing here depends on a global install;
+// LOGSEQ_CLI_DIR points at a directory whose node_modules has @logseq/cli.
+const cliCwd = process.env.LOGSEQ_CLI_DIR ?? join(here, "..");
+const logseq = (...args) =>
+  execFileSync("npx", ["-y", "@logseq/cli", ...args], { cwd: cliCwd, encoding: "utf8", shell: true, maxBuffer: 1 << 28 });
+const geml = (...args) =>
+  execFileSync(process.execPath, [GEML, ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
+
+// EDN-semantics canonical form (same as the test suite).
+function canon(v) {
+  if (Array.isArray(v)) return v.map(canon);
+  if (v !== null && typeof v === "object") {
+    if (Array.isArray(v.map)) {
+      const entries = v.map.map(([k, val]) => [canon(k), canon(val)]);
+      entries.sort((a, b) => (JSON.stringify(a[0]) < JSON.stringify(b[0]) ? -1 : 1));
+      return { map: entries };
+    }
+    if (Array.isArray(v.set)) {
+      const items = v.set.map(canon);
+      items.sort((a, b) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1));
+      return { set: items };
+    }
+    const o = {};
+    for (const k of Object.keys(v).sort()) o[k] = canon(v[k]);
+    return o;
+  }
+  return v;
+}
+const same = (a, b) => JSON.stringify(canon(parseEDNString(a))) === JSON.stringify(canon(parseEDNString(b)));
+
+rmSync(out, { recursive: true, force: true });
+mkdirSync(join(out, "geml"), { recursive: true });
+
+console.log(`1. export-edn from graph "${graph}"`);
+logseq("export-edn", "-g", graph, "-f", join(out, "export-1.edn"));
+const edn1 = readFileSync(join(out, "export-1.edn"), "utf8");
+console.log(`   ${edn1.length} bytes of EDN`);
+
+console.log("2. EDN -> GEML");
+const files = ednToGemlFiles(edn1);
+for (const [rel, text] of files) {
+  mkdirSync(dirname(join(out, "geml", rel)), { recursive: true });
+  writeFileSync(join(out, "geml", rel), text);
+}
+console.log(`   ${files.size} documents`);
+
+console.log("3. geml check on every document");
+let dirty = 0;
+for (const rel of files.keys()) {
+  try { geml("check", "--root", join(out, "geml"), join(out, "geml", rel)); }
+  catch (e) { dirty++; console.error(`   FAIL ${rel}\n${e.stdout ?? ""}${e.stderr ?? ""}`); }
+}
+if (dirty) { console.error(`   ${dirty} document(s) not clean — stopping`); process.exit(1); }
+console.log("   all clean");
+
+console.log("4. GEML -> EDN");
+const files2 = new Map();
+for (const rel of files.keys()) files2.set(rel, readFileSync(join(out, "geml", rel), "utf8"));
+const edn2 = gemlFilesToEdn(files2, lib);
+writeFileSync(join(out, "import.edn"), edn2);
+
+console.log("5. structural identity, on the real graph");
+if (!same(edn1, edn2)) { console.error("   NOT identical — diff out/export-1.edn against out/import.edn"); process.exit(1); }
+console.log("   identical (EDN semantics)");
+
+if (!doEdit) { console.log("\nround trip holds. Re-run with --edit to probe import-back semantics."); process.exit(0); }
+
+console.log("6. edit one uuid block via `geml set`, import back, validate");
+const withUuid = [...files.keys()].map((rel) => {
+  const text = files2.get(rel);
+  const unit = [...addressedUnits(text)].map((a) => a.unit).find((u) => u.kind === "block" && u.id && /^[0-9a-f-]{36}$/.test(u.id));
+  return unit ? { rel, unit } : null;
+}).find(Boolean);
+if (!withUuid) { console.log("   no uuid-bearing block in this graph (nothing referenced) — skipping the edit probe"); process.exit(0); }
+
+const target = join(out, "geml", withUuid.rel);
+// Keep the block's own head line (type, id, level) — the edit is to the BODY.
+const src = files2.get(withUuid.rel);
+const head = sliceUnit(src, withUuid.unit.span, "head").trimEnd();
+const body = sliceUnit(src, withUuid.unit.span, "body").trimEnd();
+const fence = head.match(/^=+/)[0];
+writeFileSync(join(out, "edit.txt"), `${head}\n${body} — edited by geml\n${fence}\n`);
+geml("set", target, `#${withUuid.unit.id}`, "--in", join(out, "edit.txt"), "--root", join(out, "geml"));
+console.log(`   edited #${withUuid.unit.id} in ${withUuid.rel}`);
+
+const files3 = new Map();
+for (const rel of files.keys()) files3.set(rel, readFileSync(join(out, "geml", rel), "utf8"));
+writeFileSync(join(out, "import-edited.edn"), gemlFilesToEdn(files3, lib));
+logseq("import-edn", "-g", graph, "-f", join(out, "import-edited.edn"));
+console.log("   imported");
+console.log(logseq("validate", "-g", graph).trim());
+
+console.log("7. export again — inspect out/export-2.edn to judge merge semantics");
+logseq("export-edn", "-g", graph, "-f", join(out, "export-2.edn"));
+console.log("done — compare out/export-1.edn / out/export-2.edn");