@ryanstark24/sfgraph-core 1.2.0 → 1.6.0

package/dist/storage/sqlite/snapshot-store.js

@@ -1,10 +1,70 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readSync } from "node:fs";
 import path from "node:path";
 import { StorageError, asOrgId, asQualifiedName, asSha256 } from "@ryanstark24/sfgraph-shared";
 import Database from "better-sqlite3";
 import { wrapAbiError } from "./load-better-sqlite3.js";
 import { MIGRATIONS, MigrationRunner } from "./migrations.js";
+import { advanceEdges, advanceNodes, visibleAt } from "./snapshot-versions.js";
+/** The file starts with SQLite's 16-byte header. */
+function isSqliteFile(filePath) {
+    let fd;
+    try {
+        fd = openSync(filePath, "r");
+        const b = Buffer.alloc(16);
+        return readSync(fd, b, 0, 16, 0) === 16 && b.toString("latin1") === "SQLite format 3\0";
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/**
+ * Rows in a graph file's `_sfgraph_snapshots` table; 0 when the file is not a
+ * database or has no such table, -1 when it cannot be read (callers should
+ * then assume it may hold history). Not opened read-only: a WAL-mode backup
+ * whose -shm is missing cannot be read that way.
+ */
+export function snapshotCountInFile(filePath) {
+    if (!isSqliteFile(filePath))
+        return 0;
+    let db;
+    try {
+        db = new Database(filePath, { fileMustExist: true });
+        const t = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_sfgraph_snapshots'")
+            .get();
+        if (!t)
+            return 0;
+        return db.prepare("SELECT COUNT(*) AS c FROM _sfgraph_snapshots").get().c;
+    }
+    catch {
+        return -1;
+    }
+    finally {
+        db?.close();
+    }
+}
+const CURRENT = Symbol("current");
+const NODE_COLS = (a, prefix = "") => [
+    "org_id",
+    "qualified_name",
+    "label",
+    "attributes",
+    "source_hash",
+    "first_seen_at",
+    "last_seen_at",
+    "last_modified_at",
+]
+    .map((c) => `${a}.${c}${prefix ? ` AS ${prefix}${c}` : ""}`)
+    .join(", ");
+const EDGE_COLS = (a) => ["org_id", "src_qname", "dst_qname", "rel_type", "attributes", "first_seen_at", "last_seen_at"]
+    .map((c) => `${a}.${c}`)
+    .join(", ");
+const EDGE_ORDER = "src_qname COLLATE BINARY, dst_qname COLLATE BINARY, rel_type";
 function snapshotFromRow(row) {
     return {
         id: row.id,
@@ -37,6 +97,24 @@ function edgeFromSnapshotRow(row) {
         lastSeenAt: row.last_seen_at,
     };
 }
+/**
+ * Code-point order of two keys (= SQLite BINARY on UTF-8). UTF-16 code-unit
+ * order differs only where a surrogate meets U+E000..U+FFFF; remap those.
+ */
+function cmp(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        const x = a.charCodeAt(i);
+        const y = b.charCodeAt(i);
+        if (x !== y) {
+            const fix = (c) => c >= 0xd800 && c <= 0xdfff ? c + 0x2000 : c >= 0xe000 ? c - 0x800 : c;
+            return fix(x) - fix(y);
+        }
+    }
+    return a.length - b.length;
+}
+const byNodeKey = (a, b) => cmp(a.qualified_name, b.qualified_name) || cmp(a.label, b.label);
+const byEdgeKey = (a, b) => cmp(a.src_qname, b.src_qname) || cmp(a.dst_qname, b.dst_qname) || cmp(a.rel_type, b.rel_type);
 export class SqliteSnapshotStore {
     db;
     ownsDb;
@@ -82,45 +160,73 @@ export class SqliteSnapshotStore {
         }
         this.initialized = true;
     }
+    stmts = new Map();
+    stmt(sql) {
+        let st = this.stmts.get(sql);
+        if (!st) {
+            st = this.db.prepare(sql);
+            this.stmts.set(sql, st);
+        }
+        return st;
+    }
     getNodeLabelTables() {
         const out = new Map();
-        const rows = this.db
-            .prepare("SELECT label, table_name FROM _sfgraph_node_labels")
-            .all();
+        const rows = this.stmt("SELECT label, table_name FROM _sfgraph_node_labels").all();
         for (const r of rows)
             out.set(r.label, r.table_name);
         return out;
     }
     getEdgeRelTables() {
         const out = new Map();
-        const rows = this.db
-            .prepare("SELECT rel_type, table_name FROM _sfgraph_edge_types")
-            .all();
+        const rows = this.stmt("SELECT rel_type, table_name FROM _sfgraph_edge_types").all();
         for (const r of rows)
             out.set(r.rel_type, r.table_name);
         return out;
     }
+    /**
+     * perf-03: record only what changed since the org's previous snapshot
+     * (see snapshot-versions.ts). An unchanged graph adds no version rows.
+     */
     createSnapshot(orgId, label, isAuto) {
         const id = `snap_${randomUUID()}`;
         const createdAt = Date.now();
         const apply = this.db.transaction(() => {
+            const seq = this.db.prepare("SELECT COALESCE(MAX(seq), 0) + 1 AS s FROM _sfgraph_snapshots").get().s;
+            this.db
+                .prepare("INSERT INTO _sfgraph_snapshots(id, org_id, label, created_at, is_auto, seq) VALUES (?, ?, ?, ?, ?, ?)")
+                .run(id, orgId, label, createdAt, isAuto ? 1 : 0, seq);
+            const params = { org: orgId, seq };
+            // Versions whose label / rel type no longer has a live table are gone.
             this.db
-                .prepare("INSERT INTO _sfgraph_snapshots(id, org_id, label, created_at, is_auto) VALUES (?, ?, ?, ?, ?)")
-                .run(id, orgId, label, createdAt, isAuto ? 1 : 0);
+                .prepare(`UPDATE _sfgraph_snap_nodes SET to_seq = @seq
+            WHERE org_id = @org AND to_seq IS NULL
+              AND label NOT IN (SELECT label FROM _sfgraph_node_labels)`)
+                .run(params);
+            this.db
+                .prepare(`UPDATE _sfgraph_snap_edges SET to_seq = @seq
+            WHERE org_id = @org AND to_seq IS NULL
+              AND rel_type NOT IN (SELECT rel_type FROM _sfgraph_edge_types)`)
+                .run(params);
             for (const [lbl, tbl] of this.getNodeLabelTables()) {
-                this.db
-                    .prepare(`INSERT INTO _sfgraph_node_snapshots(snapshot_id, org_id, qualified_name, label, attributes, source_hash, first_seen_at, last_seen_at, last_modified_at)
-             SELECT ?, org_id, qualified_name, ?, attributes, source_hash, first_seen_at, last_seen_at, last_modified_at FROM ${tbl} WHERE org_id = ?`)
-                    .run(id, lbl, orgId);
+                advanceNodes(this.db, {
+                    src: `${tbl} c`,
+                    srcWhere: "c.org_id = @org",
+                    labelExpr: "@lbl",
+                    labelFilter: "v.label = @lbl",
+                }, { ...params, lbl });
             }
             for (const [rt, tbl] of this.getEdgeRelTables()) {
-                this.db
-                    .prepare(`INSERT INTO _sfgraph_edge_snapshots(snapshot_id, org_id, src_qname, dst_qname, rel_type, attributes, first_seen_at, last_seen_at)
-             SELECT ?, org_id, src_qname, dst_qname, ?, attributes, first_seen_at, last_seen_at FROM ${tbl} WHERE org_id = ?`)
-                    .run(id, rt, orgId);
+                advanceEdges(this.db, {
+                    src: `${tbl} c`,
+                    srcWhere: "c.org_id = @org",
+                    relExpr: "@rt",
+                    relFilter: "v.rel_type = @rt",
+                }, { ...params, rt });
             }
         });
-        apply();
+        // review minor 1: take the write lock at BEGIN (the seq read and the
+        // version writes must not race another writer; a deferred upgrade can BUSY).
+        apply.immediate();
         return {
             id,
             orgId,
@@ -129,6 +235,58 @@ export class SqliteSnapshotStore {
             isAuto,
         };
     }
+    /**
+     * Copy the snapshot history from an older graph file (a `--rebuild` backup)
+     * into this database, so a rebuild keeps `point_in_time_diff`'s history.
+     * Copies every `_sfgraph_snap*` table of the old file (rows only; a table
+     * this database lacks is created from the old file's own SQL), using the
+     * columns both sides share. All or nothing: any error rolls the copy back.
+     * Returns how many snapshots were copied, or why nothing was copied. Only
+     * runs into an empty snapshot table (the seq numbers are kept as they are).
+     */
+    copySnapshotsFrom(filePath) {
+        const has = (schema, name) => Boolean(this.db
+            .prepare(`SELECT 1 FROM ${schema}.sqlite_master WHERE type = 'table' AND name = ?`)
+            .get(name));
+        const cols = (schema, table) => this.db.prepare(`PRAGMA ${schema}.table_info("${table}")`).all().map((c) => c.name);
+        const mine = this.db.prepare("SELECT COUNT(*) AS c FROM _sfgraph_snapshots").get();
+        if (mine.c > 0)
+            return { copied: 0, skipped: "this graph already has snapshots" };
+        // Attach only a real SQLite file: SQLite would otherwise still act on its
+        // sidecars. (Attaching a WAL-mode file checkpoints its WAL into it on
+        // detach; the rows are unchanged.)
+        if (!isSqliteFile(filePath))
+            return { copied: 0, skipped: "the old file is not a database" };
+        this.db.prepare("ATTACH DATABASE ? AS sfg_old").run(filePath);
+        try {
+            for (const t of ["_sfgraph_snapshots", "_sfgraph_snap_nodes", "_sfgraph_snap_edges"]) {
+                if (!has("sfg_old", t)) {
+                    return { copied: 0, skipped: `the old graph has no ${t} table (an older sfgraph)` };
+                }
+            }
+            if (!cols("sfg_old", "_sfgraph_snapshots").includes("seq")) {
+                return { copied: 0, skipped: "the old graph's snapshots are not versioned" };
+            }
+            const tables = this.db
+                .prepare("SELECT name, sql FROM sfg_old.sqlite_master WHERE type = 'table' AND name LIKE '\\_sfgraph\\_snap%' ESCAPE '\\' ORDER BY name")
+                .all().filter((t) => /^[A-Za-z0-9_]+$/.test(t.name));
+            const copied = this.db.transaction(() => {
+                for (const t of tables) {
+                    if (!has("main", t.name))
+                        this.db.exec(t.sql);
+                    const theirs = new Set(cols("sfg_old", t.name));
+                    const shared = cols("main", t.name).filter((c) => theirs.has(c));
+                    const list = shared.map((c) => `"${c}"`).join(", ");
+                    this.db.exec(`INSERT INTO main."${t.name}"(${list}) SELECT ${list} FROM sfg_old."${t.name}"`);
+                }
+                return this.db.prepare("SELECT COUNT(*) AS c FROM _sfgraph_snapshots").get().c;
+            })();
+            return { copied };
+        }
+        finally {
+            this.db.exec("DETACH DATABASE sfg_old");
+        }
+    }
     listSnapshots(orgId) {
         const rows = this.db
             .prepare("SELECT id, org_id, label, created_at, is_auto FROM _sfgraph_snapshots WHERE org_id = ? ORDER BY created_at DESC")
@@ -141,106 +299,348 @@ export class SqliteSnapshotStore {
             .get(id);
         return row ? snapshotFromRow(row) : null;
     }
+    /**
+     * Drop the snapshot, garbage-collect versions no remaining snapshot can see
+     * (only those visible at the deleted seq can have become unreachable), and
+     * reopen versions closed after the org's new latest snapshot so the open set
+     * is again that snapshot's state.
+     */
     deleteSnapshot(id) {
         const apply = this.db.transaction(() => {
-            this.db.prepare("DELETE FROM _sfgraph_node_snapshots WHERE snapshot_id = ?").run(id);
-            this.db.prepare("DELETE FROM _sfgraph_edge_snapshots WHERE snapshot_id = ?").run(id);
+            const row = this.db
+                .prepare("SELECT org_id, seq FROM _sfgraph_snapshots WHERE id = ?")
+                .get(id);
             this.db.prepare("DELETE FROM _sfgraph_snapshots WHERE id = ?").run(id);
+            if (!row)
+                return;
+            const params = { org: row.org_id, seq: row.seq };
+            for (const t of ["_sfgraph_snap_nodes", "_sfgraph_snap_edges"]) {
+                this.db
+                    .prepare(`DELETE FROM ${t} AS v
+              WHERE v.org_id = @org AND ${visibleAt("v", "seq")}
+                AND NOT EXISTS (SELECT 1 FROM _sfgraph_snapshots s
+                                 WHERE s.org_id = v.org_id AND s.seq >= v.from_seq
+                                   AND (v.to_seq IS NULL OR s.seq < v.to_seq))`)
+                    .run(params);
+                this.db
+                    .prepare(`UPDATE ${t} SET to_seq = NULL
+              WHERE org_id = @org AND to_seq IS NOT NULL
+                AND to_seq > (SELECT COALESCE(MAX(seq), 0) FROM _sfgraph_snapshots WHERE org_id = @org)`)
+                    .run({ org: row.org_id });
+            }
         });
-        apply();
+        // review minor 1: take the write lock at BEGIN (the seq read and the
+        // version writes must not race another writer; a deferred upgrade can BUSY).
+        apply.immediate();
     }
-    readNodes(orgId, src) {
-        const out = new Map();
-        if (src === "current") {
-            for (const [lbl, tbl] of this.getNodeLabelTables()) {
-                const rows = this.db
-                    .prepare(`SELECT org_id, qualified_name, attributes, source_hash, first_seen_at, last_seen_at, last_modified_at FROM ${tbl} WHERE org_id = ?`)
-                    .all(orgId);
-                for (const r of rows) {
-                    const nf = nodeFromSnapshotRow({ ...r, label: lbl });
-                    out.set(nf.qualifiedName, nf);
-                }
+    /**
+     * A diff side: the live graph, or a snapshot's seq. A snapshot of another
+     * org reads as empty (seq -1 matches no version), as the old
+     * `snapshot_id AND org_id` filter did.
+     */
+    side(orgId, id) {
+        if (id === "current")
+            return CURRENT;
+        const row = this.db
+            .prepare("SELECT org_id, seq FROM _sfgraph_snapshots WHERE id = ?")
+            .get(id);
+        if (!row)
+            throw new StorageError(`snapshot ${id} not found`);
+        return { seq: row.org_id === orgId ? row.seq : -1 };
+    }
+    // perf-02: diffs run in SQL; only differing rows reach JS (and JSON.parse).
+    // review I6: every query has an explicit ORDER BY, and results combined
+    // across label / rel tables are sorted by key (byNodeKey / byEdgeKey), so
+    // truncated tool output (point_in_time_diff, what_broke) is stable.
+    /** Node rows of side `x` whose qualified name (BINARY) is absent from side `y`. */
+    nodesOnlyIn(orgId, x, y) {
+        if (x === CURRENT && y === CURRENT)
+            return [];
+        const labels = this.getNodeLabelTables();
+        const out = [];
+        if (x === CURRENT) {
+            const ys = y.seq;
+            for (const [lbl, tbl] of labels) {
+                const rows = this.stmt(`SELECT c.org_id, c.qualified_name, @lbl AS label, c.attributes, c.source_hash,
+                  c.first_seen_at, c.last_seen_at, c.last_modified_at
+             FROM ${tbl} c
+            WHERE c.org_id = @org
+              AND NOT EXISTS (SELECT 1 FROM _sfgraph_snap_nodes w
+                               WHERE w.org_id = c.org_id AND w.qualified_name = c.qualified_name
+                                 AND ${visibleAt("w", "ys")})
+            ORDER BY qualified_name COLLATE BINARY, label`).all({ org: orgId, lbl, ys });
+                out.push(...rows);
             }
+            return out.sort(byNodeKey);
         }
-        else {
-            const rows = this.db
-                .prepare("SELECT org_id, qualified_name, label, attributes, source_hash, first_seen_at, last_seen_at, last_modified_at FROM _sfgraph_node_snapshots WHERE snapshot_id = ? AND org_id = ?")
-                .all(src, orgId);
-            for (const r of rows) {
-                const nf = nodeFromSnapshotRow(r);
-                out.set(nf.qualifiedName, nf);
-            }
+        const xs = x.seq;
+        if (y !== CURRENT) {
+            return this.stmt(`SELECT ${NODE_COLS("v")} FROM _sfgraph_snap_nodes v
+          WHERE v.org_id = @org AND ${visibleAt("v", "xs")}
+            AND NOT EXISTS (SELECT 1 FROM _sfgraph_snap_nodes w
+                             WHERE w.org_id = v.org_id AND w.qualified_name = v.qualified_name
+                               AND ${visibleAt("w", "ys")})
+            ORDER BY qualified_name COLLATE BINARY, label`).all({ org: orgId, xs, ys: y.seq }).sort(byNodeKey);
         }
-        return out;
+        // Snapshot rows missing from the live graph. Probe the row's own label
+        // table first; a candidate may still be live under another label (a label
+        // change), which the node index tells us.
+        const candidates = [];
+        for (const [lbl, tbl] of labels) {
+            const rows = this.stmt(`SELECT ${NODE_COLS("v")} FROM _sfgraph_snap_nodes v
+          WHERE v.org_id = @org AND v.label = @lbl AND ${visibleAt("v", "xs")}
+            AND NOT EXISTS (SELECT 1 FROM ${tbl} c
+                             WHERE c.org_id = v.org_id AND c.qualified_name = v.qualified_name
+                               AND c.qualified_name = v.qualified_name COLLATE BINARY)
+            ORDER BY qualified_name COLLATE BINARY, label`).all({ org: orgId, lbl, xs });
+            candidates.push(...rows);
+        }
+        candidates.push(...this.stmt(`SELECT ${NODE_COLS("v")} FROM _sfgraph_snap_nodes v
+          WHERE v.org_id = @org AND ${visibleAt("v", "xs")}
+            AND v.label NOT IN (SELECT label FROM _sfgraph_node_labels)
+            ORDER BY qualified_name COLLATE BINARY, label`).all({ org: orgId, xs }));
+        const idx = this.stmt("SELECT label FROM _sfgraph_node_index WHERE org_id = ? AND qualified_name = ?");
+        for (const r of candidates) {
+            const live = idx.get(orgId, r.qualified_name);
+            const tbl = live && live.label !== r.label ? labels.get(live.label) : undefined;
+            const present = tbl !== undefined &&
+                this.stmt(`SELECT 1 FROM ${tbl} WHERE org_id = ? AND qualified_name = ?
+              AND qualified_name = ? COLLATE BINARY`).get(orgId, r.qualified_name, r.qualified_name) !== undefined;
+            if (!present)
+                out.push(r);
+        }
+        return out.sort(byNodeKey);
     }
-    readEdges(orgId, src) {
-        const out = new Map();
-        const keyOf = (e) => `${e.srcQualifiedName}|${e.dstQualifiedName}|${e.relType}`;
-        if (src === "current") {
-            for (const [rt, tbl] of this.getEdgeRelTables()) {
-                const rows = this.db
-                    .prepare(`SELECT org_id, src_qname, dst_qname, attributes, first_seen_at, last_seen_at FROM ${tbl} WHERE org_id = ?`)
-                    .all(orgId);
-                for (const r of rows) {
-                    const e = edgeFromSnapshotRow({ ...r, rel_type: rt });
-                    out.set(keyOf(e), e);
-                }
+    /** Pairs present on both sides whose source hash differs. */
+    nodesChanged(orgId, from, to) {
+        if (from === CURRENT && to === CURRENT)
+            return [];
+        const out = [];
+        const split = (r) => {
+            const a = {};
+            const b = {};
+            for (const [k, v] of Object.entries(r)) {
+                if (k.startsWith("a_"))
+                    a[k.slice(2)] = v;
+                else if (k.startsWith("b_"))
+                    b[k.slice(2)] = v;
             }
+            return [a, b];
+        };
+        if (from !== CURRENT && to !== CURRENT) {
+            if (from.seq === to.seq)
+                return [];
+            const rows = this.stmt(`SELECT ${NODE_COLS("a", "a_")}, ${NODE_COLS("b", "b_")}
+           FROM _sfgraph_snap_nodes a
+           JOIN _sfgraph_snap_nodes b
+             ON b.org_id = a.org_id AND b.qualified_name = a.qualified_name
+            AND ${visibleAt("b", "ts")}
+          WHERE a.org_id = @org AND ${visibleAt("a", "fs")} AND NOT ${visibleAt("a", "ts")}
+            AND b.source_hash <> a.source_hash COLLATE BINARY
+          ORDER BY a.qualified_name, a.label, b.label`).all({ org: orgId, fs: from.seq, ts: to.seq });
+            for (const r of rows) {
+                const [before, after] = split(r);
+                out.push({ before, after });
+            }
+            return out.sort((p, q) => byNodeKey(p.before, q.before) || byNodeKey(p.after, q.after));
         }
-        else {
-            const rows = this.db
-                .prepare("SELECT org_id, src_qname, dst_qname, rel_type, attributes, first_seen_at, last_seen_at FROM _sfgraph_edge_snapshots WHERE snapshot_id = ? AND org_id = ?")
-                .all(src, orgId);
+        // CROSS JOIN pins the live table as the outer loop: with v outer, the
+        // BINARY `v.qualified_name` cannot seek c's NOCASE key and every version
+        // row scanned the whole label table (50k nodes: ~230 s). Pairs match by
+        // qname across labels on purpose: a label move with a new hash is
+        // "changed", as with the old full copies.
+        const snapSeq = (from === CURRENT ? to : from);
+        for (const [lbl, tbl] of this.getNodeLabelTables()) {
+            const rows = this.stmt(`SELECT c.org_id AS a_org_id, c.qualified_name AS a_qualified_name, @lbl AS a_label,
+                c.attributes AS a_attributes, c.source_hash AS a_source_hash,
+                c.first_seen_at AS a_first_seen_at, c.last_seen_at AS a_last_seen_at,
+                c.last_modified_at AS a_last_modified_at, ${NODE_COLS("v", "b_")}
+           FROM ${tbl} c
+           CROSS JOIN _sfgraph_snap_nodes v
+             ON v.org_id = c.org_id AND v.qualified_name = c.qualified_name
+            AND ${visibleAt("v", "ss")}
+          WHERE c.org_id = @org AND c.source_hash <> v.source_hash COLLATE BINARY
+          ORDER BY c.qualified_name COLLATE BINARY, v.label`).all({ org: orgId, lbl, ss: snapSeq.seq });
             for (const r of rows) {
-                const e = edgeFromSnapshotRow(r);
-                out.set(keyOf(e), e);
+                const [live, snapped] = split(r);
+                out.push(from === CURRENT ? { before: live, after: snapped } : { before: snapped, after: live });
             }
         }
-        return out;
+        return out.sort((p, q) => byNodeKey(p.before, q.before) || byNodeKey(p.after, q.after));
+    }
+    /**
+     * The queries whose union is the edge rows of side `x` whose (src, dst, rel)
+     * key (BINARY) is absent from side `y`. Each part is `FROM ... WHERE ...`
+     * plus its select list and bindings, so a caller can fetch all rows, the
+     * first n rows (`ORDER BY ... LIMIT`) or a `COUNT(*)` from the same SQL.
+     * The version key / rel indexes cover every column these predicates read
+     * (schema v15), so a count never touches the version table's rows.
+     */
+    edgeParts(orgId, x, y) {
+        if (x === CURRENT && y === CURRENT)
+            return [];
+        const rels = this.getEdgeRelTables();
+        const parts = [];
+        if (x === CURRENT) {
+            const ys = y.seq;
+            for (const [rt, tbl] of rels) {
+                parts.push({
+                    cols: `c.org_id, c.src_qname, c.dst_qname, @rt AS rel_type, c.attributes,
+                    c.first_seen_at, c.last_seen_at`,
+                    body: `FROM ${tbl} c
+              WHERE c.org_id = @org
+                AND NOT EXISTS (SELECT 1 FROM _sfgraph_snap_edges w
+                                 WHERE w.org_id = c.org_id AND w.src_qname = c.src_qname
+                                   AND w.dst_qname = c.dst_qname AND w.rel_type = @rt
+                                   AND ${visibleAt("w", "ys")})`,
+                    params: { org: orgId, rt, ys },
+                });
+            }
+            return parts;
+        }
+        const xs = x.seq;
+        if (y !== CURRENT) {
+            return [
+                {
+                    cols: EDGE_COLS("v"),
+                    body: `FROM _sfgraph_snap_edges v
+          WHERE v.org_id = @org AND ${visibleAt("v", "xs")}
+            AND NOT EXISTS (SELECT 1 FROM _sfgraph_snap_edges w
+                             WHERE w.org_id = v.org_id AND w.src_qname = v.src_qname
+                               AND w.dst_qname = v.dst_qname AND w.rel_type = v.rel_type
+                               AND ${visibleAt("w", "ys")})`,
+                    params: { org: orgId, xs, ys: y.seq },
+                },
+            ];
+        }
+        // INDEXED BY: with ORDER BY ... LIMIT the planner may prefer walking the
+        // key index (already in src/dst order) over the whole org's versions,
+        // once per rel type; the rel index reads only this rel's rows.
+        for (const [rt, tbl] of rels) {
+            parts.push({
+                cols: EDGE_COLS("v"),
+                body: `FROM _sfgraph_snap_edges v INDEXED BY _sfgraph_snap_edges_rel
+            WHERE v.org_id = @org AND v.rel_type = @rt AND ${visibleAt("v", "xs")}
+              AND NOT EXISTS (SELECT 1 FROM ${tbl} c
+                               WHERE c.org_id = v.org_id AND c.src_qname = v.src_qname
+                                 AND c.dst_qname = v.dst_qname
+                                 AND c.src_qname = v.src_qname COLLATE BINARY
+                                 AND c.dst_qname = v.dst_qname COLLATE BINARY)`,
+                params: { org: orgId, rt, xs },
+            });
+        }
+        parts.push({
+            cols: EDGE_COLS("v"),
+            body: `FROM _sfgraph_snap_edges v
+          WHERE v.org_id = @org AND ${visibleAt("v", "xs")}
+            AND v.rel_type NOT IN (SELECT rel_type FROM _sfgraph_edge_types)`,
+            params: { org: orgId, xs },
+        });
+        return parts;
+    }
+    /** Edge rows of side `x` whose (src, dst, rel) key (BINARY) is absent from side `y`. */
+    edgesOnlyIn(orgId, x, y) {
+        const out = [];
+        for (const p of this.edgeParts(orgId, x, y)) {
+            out.push(...this.stmt(`SELECT ${p.cols} ${p.body} ORDER BY ${EDGE_ORDER}`).all(p.params));
+        }
+        return out.sort(byEdgeKey);
+    }
+    /**
+     * The first `limit` rows of {@link edgesOnlyIn} (same order) and its exact
+     * length, without materialising the rest: each part is counted in SQL and,
+     * when non-empty, returns at most `limit` rows in key order. `counts` holds
+     * per-part counts already known: `exact` ones are used as is; an `upper`
+     * bound of 0 proves the part empty, any other bound is recounted.
+     */
+    edgesOnlyInPage(orgId, x, y, limit, counts) {
+        const lim = Math.max(0, Math.floor(limit));
+        const rows = [];
+        let count = 0;
+        for (const [i, p] of this.edgeParts(orgId, x, y).entries()) {
+            // Count first (index-only); most parts are empty and need no page.
+            const n = counts?.exact?.[i] ??
+                (counts?.upper?.[i] === 0
+                    ? 0
+                    : this.stmt(`SELECT COUNT(*) AS n ${p.body}`).get(p.params).n);
+            count += n;
+            if (n === 0 || lim === 0)
+                continue;
+            rows.push(...this.stmt(`SELECT ${p.cols} ${p.body} ORDER BY ${EDGE_ORDER} LIMIT @lim`).all({
+                ...p.params,
+                lim,
+            }));
+        }
+        return { rows: rows.sort(byEdgeKey).slice(0, lim), count };
+    }
+    /**
+     * Per rel type (the order of `edgeParts(snap, CURRENT)`, without its last
+     * unregistered-rel part), an upper bound on the number of snapshot edges
+     * absent from the live table, from the live-only count `curOnly` (the order
+     * of `edgeParts(CURRENT, snap)`): |snap| - (|live| - |live \ snap|).
+     * |live| - |live \ snap| counts live rows with a matching snapshot row;
+     * live keys are unique, so at least as many snapshot rows match, and the
+     * bound holds whatever the snapshot holds. A bound of 0 proves the part
+     * empty without the anti-join; any other bound is recounted.
+     */
+    snapOnlyUpperBounds(orgId, snapSeq, curOnly) {
+        return [...this.getEdgeRelTables()].map(([rt, tbl], i) => {
+            const live = this.stmt(`SELECT COUNT(*) AS n FROM ${tbl} WHERE org_id = @org`).get({ org: orgId }).n;
+            const snap = this.stmt(`SELECT COUNT(*) AS n FROM _sfgraph_snap_edges v INDEXED BY _sfgraph_snap_edges_rel
+            WHERE v.org_id = @org AND v.rel_type = @rt AND ${visibleAt("v", "xs")}`).get({ org: orgId, rt, xs: snapSeq }).n;
+            return Math.max(0, snap - (live - (curOnly[i] ?? 0)));
+        });
+    }
+    /** Index-only count of every part of {@link edgeParts}(x, y). */
+    edgePartCounts(orgId, x, y) {
+        return this.edgeParts(orgId, x, y).map((p) => this.stmt(`SELECT COUNT(*) AS n ${p.body}`).get(p.params).n);
     }
     diffNodes(orgId, fromId, toId) {
-        if (fromId !== "current" && !this.getSnapshot(fromId)) {
-            throw new StorageError(`snapshot ${fromId} not found`);
-        }
-        if (toId !== "current" && !this.getSnapshot(toId)) {
-            throw new StorageError(`snapshot ${toId} not found`);
-        }
-        const from = this.readNodes(orgId, fromId);
-        const to = this.readNodes(orgId, toId);
-        const added = [];
-        const removed = [];
-        const changed = [];
-        for (const [qn, t] of to) {
-            const f = from.get(qn);
-            if (!f)
-                added.push(t);
-            else if (f.sourceHash !== t.sourceHash)
-                changed.push({ before: f, after: t });
-        }
-        for (const [qn, f] of from) {
-            if (!to.has(qn))
-                removed.push(f);
-        }
-        return { added, removed, changed };
+        const from = this.side(orgId, fromId);
+        const to = this.side(orgId, toId);
+        return {
+            added: this.nodesOnlyIn(orgId, to, from).map(nodeFromSnapshotRow),
+            removed: this.nodesOnlyIn(orgId, from, to).map(nodeFromSnapshotRow),
+            changed: this.nodesChanged(orgId, from, to).map((c) => ({
+                before: nodeFromSnapshotRow(c.before),
+                after: nodeFromSnapshotRow(c.after),
+            })),
+        };
     }
     diffEdges(orgId, fromId, toId) {
-        if (fromId !== "current" && !this.getSnapshot(fromId)) {
-            throw new StorageError(`snapshot ${fromId} not found`);
-        }
-        if (toId !== "current" && !this.getSnapshot(toId)) {
-            throw new StorageError(`snapshot ${toId} not found`);
-        }
-        const from = this.readEdges(orgId, fromId);
-        const to = this.readEdges(orgId, toId);
-        const added = [];
-        const removed = [];
-        for (const [k, t] of to)
-            if (!from.has(k))
-                added.push(t);
-        for (const [k, f] of from)
-            if (!to.has(k))
-                removed.push(f);
-        return { added, removed };
+        const from = this.side(orgId, fromId);
+        const to = this.side(orgId, toId);
+        return {
+            added: this.edgesOnlyIn(orgId, to, from).map(edgeFromSnapshotRow),
+            removed: this.edgesOnlyIn(orgId, from, to).map(edgeFromSnapshotRow),
+        };
+    }
+    diffEdgesPage(orgId, fromId, toId, limit) {
+        // One read transaction: every count and page sees the same state.
+        return this.db.transaction(() => {
+            const from = this.side(orgId, fromId);
+            const to = this.side(orgId, toId);
+            let addedCounts;
+            let removedCounts;
+            if (from !== CURRENT && to === CURRENT) {
+                const exact = this.edgePartCounts(orgId, to, from);
+                addedCounts = { exact };
+                removedCounts = { upper: this.snapOnlyUpperBounds(orgId, from.seq, exact) };
+            }
+            else if (from === CURRENT && to !== CURRENT) {
+                const exact = this.edgePartCounts(orgId, from, to);
+                removedCounts = { exact };
+                addedCounts = { upper: this.snapOnlyUpperBounds(orgId, to.seq, exact) };
+            }
+            const added = this.edgesOnlyInPage(orgId, to, from, limit, addedCounts);
+            const removed = this.edgesOnlyInPage(orgId, from, to, limit, removedCounts);
+            return {
+                added: added.rows.map(edgeFromSnapshotRow),
+                removed: removed.rows.map(edgeFromSnapshotRow),
+                addedCount: added.count,
+                removedCount: removed.count,
+            };
+        })();
     }
     prune(orgId, retainDays) {
         const cutoff = Date.now() - retainDays * 86_400_000;