@kontourai/flow-agents 2.4.0 → 3.1.0

package/kits/knowledge/providers/neo4j/integration.test.js

@@ -0,0 +1,122 @@
+/**
+ * neo4j provider — LIVE integration test (gated).
+ *
+ * Runs against a real Neo4j Community instance ONLY when NEO4J_URI is set and
+ * reachable; otherwise it SKIPS LOUDLY (CI has no Neo4j — the CI proof is the
+ * unit tests + conformance with the injected fake driver). To run locally:
+ *
+ *   docker run -d --name kg-neo4j -p 7474:7474 -p 7687:7687 \
+ *     -e NEO4J_AUTH=neo4j/testpassword neo4j:5-community
+ *   NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=testpassword \
+ *     node --test kits/knowledge/providers/neo4j/integration.test.js
+ *
+ * Proves end-to-end what the fake driver can only approximate: real MERGE
+ * idempotency counters (AC1) and the five canonical queries executing as LIVE
+ * Cypher (AC3), asserted to agree with the portable JS backend (parity).
+ *
+ * @module providers/neo4j/integration.test
+ */
+
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Neo4jProvider } from "./index.js";
+import { syncToNeo4j } from "./sync.js";
+import { resolveNeo4jConfig, createDriver, isReachable } from "./connection.js";
+import * as jsq from "./graph-queries.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const GRAPH = JSON.parse(fs.readFileSync(path.join(__dirname, "fixtures", "spike-ground-truth.json"), "utf8"));
+
+const config = resolveNeo4jConfig();
+let driver = null;
+let live = false;
+
+before(async () => {
+  if (!config) return;
+  driver = await createDriver(config);
+  live = await isReachable(driver);
+});
+
+after(async () => {
+  if (driver) await driver.close();
+});
+
+describe("neo4j LIVE integration", () => {
+  test("live Neo4j round-trip, idempotent sync (AC1) and canonical Cypher queries (AC3)", async (t) => {
+    if (!config) {
+      t.skip("SKIP (loud): NEO4J_URI unset — live Neo4j integration not run. See file header to run locally.");
+      return;
+    }
+    if (!live) {
+      t.skip(`SKIP (loud): Neo4j configured (${config.uri}) but not reachable — live integration not run.`);
+      return;
+    }
+
+    const graph = { nodes: JSON.parse(JSON.stringify(GRAPH.nodes)), edges: JSON.parse(JSON.stringify(GRAPH.edges)) };
+
+    // Clean slate.
+    {
+      const s = driver.session({ database: config.database });
+      try {
+        await s.run("MATCH (n) DETACH DELETE n");
+      } finally {
+        await s.close();
+      }
+    }
+
+    // AC1: first sync writes; second reports zero; forced re-sync also zero.
+    const first = await syncToNeo4j({ driver, database: config.database, graph });
+    assert.ok(first.writes > 0, "first live sync must write");
+    const second = await syncToNeo4j({ driver, database: config.database, graph });
+    assert.equal(second.writes, 0, "second live sync must report zero writes (MERGE idempotency)");
+    const forced = await syncToNeo4j({ driver, database: config.database, graph, force: true });
+    assert.equal(forced.writes, 0, "forced live re-sync of identical data must produce zero writes");
+
+    const provider = new Neo4jProvider({ driver, database: config.database, agent: "integration" });
+    assert.equal(provider._cypherAnalytics, true, "live driver must use the Cypher analytics backend");
+
+    // Read side round-trips.
+    const nodes = await provider.readNodes();
+    assert.ok(nodes.length >= GRAPH.nodes.length);
+
+    // AC3 via LIVE Cypher, asserted equal to the JS oracle over the same graph.
+    const blockers = await provider.transitiveBlockers("issue:313");
+    assert.deepEqual(
+      blockers.map((b) => b.id).sort(),
+      ["issue:310", "issue:312"],
+      "Q1 live Cypher: #313 blockers = {#310,#312}, not #317",
+    );
+
+    const contradictions = await provider.contradictionCandidates();
+    assert.ok(
+      contradictions.some((c) => c.a_id === "decision:adr-0007" && c.b_id === "decision:adr-0007b"),
+      "Q2 live Cypher: ADR-0007 collision flagged",
+    );
+
+    const orphans = await provider.orphans();
+    const orphanIds = orphans.map((o) => o.id);
+    assert.ok(orphanIds.includes("decision:orphan-adr"), "Q3 live Cypher: stale decision orphan");
+    assert.ok(!orphanIds.includes("session:s1"), "Q3 live Cypher: leaf types excluded");
+
+    const dups = await provider.duplicateCandidates();
+    assert.ok(
+      dups.some(
+        (d) =>
+          (d.a_id === "issue:traverse-8" && d.b_id === "issue:traverse-14") ||
+          (d.a_id === "issue:traverse-14" && d.b_id === "issue:traverse-8"),
+      ),
+      "Q4 live Cypher: stemmed dup catches the traverse pair",
+    );
+    // Parity: the same stemmed dup is (not) found by exact tokens in JS.
+    const jsDups = jsq.duplicateCandidates(graph, { threshold: 0.7 });
+    const jsHit = jsDups.find((d) => d.a_id.startsWith("issue:traverse") && d.b_id.startsWith("issue:traverse"));
+    assert.ok(jsHit && jsHit.caught_only_by_stemming, "JS oracle agrees: caught only by stemming");
+
+    const sp = await provider.shortestPath("decision:adr-0011", "decision:adr-0021");
+    assert.equal(sp.length, 2, "Q5 live Cypher: shortest path length 2");
+  });
+});

package/kits/knowledge/providers/neo4j/neo4j.test.js

@@ -0,0 +1,219 @@
+/**
+ * neo4j provider — unit tests (CI-safe, no Docker, injected fake driver).
+ *
+ * Covers the parts of issue #327 that do NOT need a live server:
+ *   - sync idempotency (AC1): writes>0 on first sync, 0 on re-sync, 0 on a
+ *     FORCED re-sync (hash-guard) — proven against the fake driver's counters.
+ *   - canonical queries (AC3): the five spike queries over the ground-truth
+ *     fixture reproduce the spike's results, incl. the stemmed-dup case.
+ *   - marker tolerance: a throwing provider does not kill the sync.
+ *   - graceful degradation (AC4): selection falls back to file providers with a
+ *     clear one-line message when no Neo4j is reachable / configured.
+ *   - proposals-only write.
+ *
+ * Run: node --test kits/knowledge/providers/neo4j/neo4j.test.js
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Neo4jProvider } from "./index.js";
+import { syncToNeo4j, materializeGraph, planSync, computeDigest } from "./sync.js";
+import { selectKnowledgeProvider } from "./connection.js";
+import { makeFakeDriver } from "./fake-driver.js";
+import * as jsq from "./graph-queries.js";
+import { loadSchemas } from "../lib/model.js";
+import { validate } from "../lib/schema-validate.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const GRAPH = JSON.parse(fs.readFileSync(path.join(__dirname, "fixtures", "spike-ground-truth.json"), "utf8"));
+const schemas = loadSchemas();
+
+function fixtureGraph() {
+  return { nodes: JSON.parse(JSON.stringify(GRAPH.nodes)), edges: JSON.parse(JSON.stringify(GRAPH.edges)) };
+}
+
+describe("neo4j sync — idempotency (AC1)", () => {
+  test("first sync writes; second sync reports zero writes; forced re-sync also zero (hash-guard)", async () => {
+    const driver = makeFakeDriver();
+    const graph = fixtureGraph();
+
+    const first = await syncToNeo4j({ driver, graph });
+    assert.ok(first.writes > 0, `expected writes on first sync, got ${first.writes}`);
+    assert.equal(first.unchanged, false);
+    assert.ok(first.digest && first.snapshot.synced_at);
+
+    const second = await syncToNeo4j({ driver, graph });
+    assert.equal(second.writes, 0, "second sync must report zero writes");
+    assert.equal(second.unchanged, true);
+
+    // Force past the digest short-circuit: the hash-guarded MERGE must STILL
+    // produce zero created nodes/rels and zero property sets on identical data.
+    const forced = await syncToNeo4j({ driver, graph, force: true });
+    assert.equal(forced.writes, 0, "forced re-sync of identical data must produce zero writes");
+  });
+
+  test("planSync is a pure no-op when the digest is unchanged", () => {
+    const graph = fixtureGraph();
+    const digest = computeDigest(graph);
+    const plan = planSync(graph, digest);
+    assert.equal(plan.unchanged, true);
+    assert.equal(plan.statements.length, 0);
+    const changed = planSync(graph, "different-digest");
+    assert.equal(changed.unchanged, false);
+    assert.ok(changed.statements.length > 0);
+  });
+});
+
+describe("neo4j read side round-trips through the (fake) driver", () => {
+  test("synced graph reads back as schema-valid nodes/edges", async () => {
+    const driver = makeFakeDriver();
+    await syncToNeo4j({ driver, graph: fixtureGraph() });
+    const provider = new Neo4jProvider({ driver });
+
+    const nodes = await provider.readNodes();
+    assert.ok(nodes.length > 0);
+    for (const n of nodes) {
+      const { valid, errors } = validate(n, schemas.node);
+      assert.ok(valid, `node ${n.id} invalid: ${errors.join(", ")}`);
+    }
+    const edges = await provider.readEdges();
+    for (const e of edges) {
+      const { valid, errors } = validate(e, schemas.edge);
+      assert.ok(valid, `edge ${e.id} invalid: ${errors.join(", ")}`);
+    }
+    // Edges to nodes present in the fixture materialize; all 8 fixture edges have
+    // resolvable endpoints, so the view keeps them.
+    assert.equal(edges.length, GRAPH.edges.length);
+  });
+});
+
+describe("neo4j canonical queries reproduce the spike ground truth (AC3)", () => {
+  const provider = new Neo4jProvider({ sourceGraph: fixtureGraph() });
+
+  test("Q1 transitive blockers of #313 = {#312 OPEN, #310 CLOSED}, NOT #317", async () => {
+    const blockers = await provider.transitiveBlockers("issue:313");
+    const ids = blockers.map((b) => b.id).sort();
+    assert.deepEqual(ids, ["issue:310", "issue:312"]);
+    assert.equal(blockers.find((b) => b.id === "issue:310").state, "CLOSED");
+    assert.equal(blockers.find((b) => b.id === "issue:312").state, "OPEN");
+    assert.ok(!ids.includes("issue:317"), "the spike headline: no #313 -> #317 edge exists");
+  });
+
+  test("Q2 contradiction candidates catch the ADR-0007 collision", async () => {
+    const cands = await provider.contradictionCandidates();
+    const hit = cands.find((c) => c.a_id === "decision:adr-0007" && c.b_id === "decision:adr-0007b");
+    assert.ok(hit, "ADR-0007 vs ADR-0007b (same subject, divergent status) must be flagged");
+    // A different-subject decision pair must NOT be a contradiction.
+    assert.ok(!cands.some((c) => c.a_id === "decision:adr-0011" && c.b_id === "decision:adr-0021"));
+  });
+
+  test("Q3 orphans are node-type aware: the stale decision surfaces, leaf types do not", async () => {
+    const orphans = await provider.orphans();
+    const ids = orphans.map((o) => o.id);
+    assert.ok(ids.includes("decision:orphan-adr"), "the undiscoverable decision is a meaningful orphan");
+    assert.ok(!ids.includes("session:s1"), "sessions are source-only leaves — never flagged");
+    assert.ok(!ids.includes("learning:l1"), "learnings are source-only leaves — never flagged");
+  });
+
+  test("Q4 duplicate detection needs stemming: traverse#14 ~ #8 caught only by stemming", async () => {
+    const dups = await provider.duplicateCandidates();
+    const hit = dups.find(
+      (d) =>
+        (d.a_id === "issue:traverse-8" && d.b_id === "issue:traverse-14") ||
+        (d.a_id === "issue:traverse-14" && d.b_id === "issue:traverse-8"),
+    );
+    assert.ok(hit, "the known traverse duplicate must be detected");
+    assert.equal(hit.caught_only_by_stemming, true, "exact tokens miss it; stemming catches it");
+    assert.ok(hit.exact_similarity < 0.7 && hit.stemmed_similarity >= 0.7);
+  });
+
+  test("Q5 shortest path between two decisions is length 2 through a shared node", async () => {
+    const sp = await provider.shortestPath("decision:adr-0011", "decision:adr-0021");
+    assert.ok(sp, "a path must exist");
+    assert.equal(sp.length, 2);
+    assert.equal(sp.path[0], "decision:adr-0011");
+    assert.equal(sp.path[sp.path.length - 1], "decision:adr-0021");
+  });
+
+  test("naive exact-token duplicate detection MISSES the traverse dup (the spike's finding)", () => {
+    // Direct evidence of the finding: exact tokens produce no cross-threshold hit
+    // for the traverse pair, stemming does.
+    const g = { nodes: fixtureGraph().nodes.filter((n) => n.id.startsWith("issue:traverse")), edges: [] };
+    const dups = jsq.duplicateCandidates(g, { threshold: 0.7 });
+    assert.equal(dups.length, 1);
+    assert.equal(dups[0].exact_similarity, 0);
+    assert.ok(dups[0].stemmed_similarity >= 0.7);
+  });
+});
+
+describe("marker tolerance (spike finding 3)", () => {
+  test("a provider that throws while reading does not kill the sync", async () => {
+    const good = new Neo4jProvider({ sourceGraph: fixtureGraph() });
+    const exploding = {
+      id: "work-item",
+      async readGraph() {
+        throw new Error("simulated malformed metadata marker: 3/19 failed JSON.parse");
+      },
+    };
+    const mat = await materializeGraph([good, exploding]);
+    assert.ok(mat.nodes.length > 0, "the healthy provider's graph still materialized");
+    assert.equal(mat.errors.length, 1);
+    assert.match(mat.errors[0].error, /malformed metadata marker/);
+  });
+});
+
+describe("graceful degradation (AC4)", () => {
+  test("neo4j selected but NEO4J_URI unset -> file providers with a clear message", async () => {
+    const msgs = [];
+    const result = await selectKnowledgeProvider({
+      preference: "neo4j",
+      env: {},
+      fileProviders: async () => [{ id: "git-repo" }],
+      log: (m) => msgs.push(m),
+    });
+    assert.equal(result.provider, "file");
+    assert.equal(result.providers[0].id, "git-repo");
+    assert.match(msgs[0], /NEO4J_URI is unset/);
+  });
+
+  test("neo4j reachable path selects the neo4j provider", async () => {
+    const driver = makeFakeDriver();
+    const result = await selectKnowledgeProvider({
+      preference: "neo4j",
+      env: { NEO4J_URI: "bolt://localhost:7687" },
+      driver,
+      fileProviders: async () => [{ id: "git-repo" }],
+      neo4jFactory: async ({ driver: d }) => new Neo4jProvider({ driver: d }),
+    });
+    assert.equal(result.provider, "neo4j");
+    assert.ok(result.graph instanceof Neo4jProvider);
+  });
+
+  test("default preference is file (graph is opt-in only)", async () => {
+    const result = await selectKnowledgeProvider({
+      env: {},
+      fileProviders: async () => [{ id: "git-repo" }],
+    });
+    assert.equal(result.provider, "file");
+  });
+});
+
+describe("proposals-only write", () => {
+  test("proposeWrite returns a schema-valid 'proposed' proposal and mutates nothing", async () => {
+    const driver = makeFakeDriver();
+    await syncToNeo4j({ driver, graph: fixtureGraph() });
+    const provider = new Neo4jProvider({ driver });
+    const before = await provider.readNodes();
+    const p = await provider.proposeWrite({ kind: "create-node", type: "note", title: "Proposed" });
+    const { valid, errors } = validate(p, schemas.proposal);
+    assert.ok(valid, `proposal invalid: ${errors.join(", ")}`);
+    assert.equal(p.status, "proposed");
+    assert.equal(p.provider, "neo4j");
+    const after = await provider.readNodes();
+    assert.equal(after.length, before.length, "proposeWrite must not mutate the store");
+  });
+});

package/kits/knowledge/providers/neo4j/sync.js

@@ -0,0 +1,235 @@
+/**
+ * Sync / materialize: import the file/work-item providers into Neo4j.
+ *
+ * The file stores remain the SOURCE OF TRUTH; the graph is a queryable
+ * materialized view. Sync reuses the #317 providers as READERS (no forked
+ * extractors) and MERGEs their combined graph into Neo4j with MERGE semantics,
+ * so a re-sync of unchanged data reports zero writes (AC1). A snapshot digest +
+ * timestamp is recorded on the graph so the second run can short-circuit and so
+ * the graph is point-in-time attributable.
+ *
+ * Marker tolerance (spike finding 3: 3/19 metadata markers failed JSON.parse in
+ * the wild): a provider that throws while reading MUST NOT kill the whole sync.
+ * Each provider is read behind a guard that falls back to an empty contribution
+ * and records the error; the work-item provider already falls back from a
+ * malformed metadata marker to prose refs, and this guard covers the rest.
+ *
+ * Pure planning (planSync/computeDigest) is separated from IO (syncToNeo4j) so
+ * idempotency is unit-testable with no driver and no Docker.
+ *
+ * @module providers/neo4j/sync
+ */
+
+import { createHash } from "node:crypto";
+import {
+  typeToLabel,
+  edgeTypeToRel,
+  nodeToProps,
+  edgeToProps,
+  SNAPSHOT_LABEL,
+  SNAPSHOT_ID,
+  READ_SNAPSHOT_CYPHER,
+} from "./cypher.js";
+
+/** Deterministic JSON (sorted keys) for hashing. */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * The graph is a materialized view keyed on CONTENT, not on when it was read.
+ * Provenance carries volatile fields (retrieved_at, agent) that change every
+ * read — including them would defeat idempotency (a re-sync of unchanged stores
+ * would rewrite every element). Strip them for identity; the snapshot's
+ * synced_at records the point-in-time separately.
+ */
+function contentIdentity(el) {
+  const clone = JSON.parse(JSON.stringify(el));
+  if (clone.provenance) {
+    delete clone.provenance.retrieved_at;
+    delete clone.provenance.agent;
+  }
+  return clone;
+}
+
+/** Content hash of a single node/edge (drives the idempotent hash-guarded SET). */
+export function hashElement(el) {
+  return createHash("sha256").update(canonical(contentIdentity(el))).digest("hex").slice(0, 16);
+}
+
+/** Digest of the whole materialized graph (drives the zero-write short-circuit). */
+export function computeDigest(graph) {
+  const nodes = [...(graph.nodes || [])].map(contentIdentity).sort((a, b) => a.id.localeCompare(b.id));
+  const edges = [...(graph.edges || [])].map(contentIdentity).sort((a, b) => a.id.localeCompare(b.id));
+  return createHash("sha256").update(canonical({ nodes, edges })).digest("hex");
+}
+
+/** Read one provider's graph behind a guard; never let one provider kill sync. */
+async function safeReadGraph(provider, errors) {
+  try {
+    const g = await provider.readGraph();
+    return { nodes: g.nodes || [], edges: g.edges || [] };
+  } catch (err) {
+    errors.push({ provider: provider?.id || provider?.constructor?.name || "unknown", error: String(err && err.message || err) });
+    return { nodes: [], edges: [] };
+  }
+}
+
+/**
+ * Materialize the combined graph from the provider readers. Dedupes nodes and
+ * edges by id (last write wins on id collision across providers).
+ * @param {object[]} providers  #317 provider instances (vault, git-repo, work-item, …)
+ * @returns {Promise<{ nodes:object[], edges:object[], errors:object[] }>}
+ */
+export async function materializeGraph(providers) {
+  const errors = [];
+  const nodeById = new Map();
+  const edgeById = new Map();
+  for (const provider of providers) {
+    const { nodes, edges } = await safeReadGraph(provider, errors);
+    for (const n of nodes) nodeById.set(n.id, n);
+    for (const e of edges) edgeById.set(e.id, e);
+  }
+  return { nodes: [...nodeById.values()], edges: [...edgeById.values()], errors };
+}
+
+/**
+ * Pure sync plan. Given the materialized graph and the prior snapshot digest,
+ * decide whether anything changed and produce the parameterized MERGE
+ * statements. When the digest is unchanged, the plan is a no-op (AC1: second run
+ * reports zero writes) unless `force` is set.
+ *
+ * @param {{nodes:object[],edges:object[]}} graph
+ * @param {string|null} priorDigest
+ * @param {object} [options]
+ * @param {boolean} [options.force=false] emit statements even when unchanged
+ * @returns {{ digest:string, unchanged:boolean, statements:{cypher:string,params:object}[] }}
+ */
+export function planSync(graph, priorDigest, options = {}) {
+  const digest = computeDigest(graph);
+  const unchanged = digest === priorDigest;
+  if (unchanged && !options.force) {
+    return { digest, unchanged, statements: [] };
+  }
+
+  const statements = [];
+
+  // Nodes grouped by contract type -> one MERGE per Neo4j label. Hash-guarded
+  // SET so an unchanged node produces zero propertiesSet on re-run.
+  const nodesByLabel = new Map();
+  for (const n of graph.nodes || []) {
+    const label = typeToLabel(n.type);
+    if (!nodesByLabel.has(label)) nodesByLabel.set(label, []);
+    nodesByLabel.get(label).push(nodeToProps(n, hashElement(n)));
+  }
+  for (const [label, rows] of nodesByLabel) {
+    statements.push({
+      cypher: `UNWIND $rows AS r MERGE (n:${label} {id:r.id}) WITH n, r WHERE coalesce(n._kg_hash,'') <> r._kg_hash SET n += r`,
+      params: { rows },
+    });
+  }
+
+  // Edges grouped by rel type. Endpoints matched by id regardless of label
+  // (spike: polyglot property bags "just work"); edges to a not-yet-synced node
+  // are skipped by the MATCH (external/dangling refs stay out of the view).
+  const edgesByRel = new Map();
+  for (const e of graph.edges || []) {
+    const rel = edgeTypeToRel(e.type);
+    if (!edgesByRel.has(rel)) edgesByRel.set(rel, []);
+    edgesByRel.get(rel).push(edgeToProps(e, hashElement(e)));
+  }
+  for (const [rel, rows] of edgesByRel) {
+    statements.push({
+      cypher: `UNWIND $rows AS r MATCH (a {id:r.from}) MATCH (b {id:r.to}) MERGE (a)-[x:${rel} {id:r.id}]->(b) WITH x, r WHERE coalesce(x._kg_hash,'') <> r._kg_hash SET x += r`,
+      params: { rows },
+    });
+  }
+
+  return { digest, unchanged, statements };
+}
+
+/** Read the prior snapshot digest from Neo4j (null if never synced). */
+async function readPriorDigest(session) {
+  const res = await session.run(READ_SNAPSHOT_CYPHER, { id: SNAPSHOT_ID });
+  const rec = res.records && res.records[0];
+  if (!rec) return null;
+  const props = rec.get("props");
+  return (props && props.digest) || null;
+}
+
+function sumWrites(counters) {
+  const u = typeof counters.updates === "function" ? counters.updates() : counters;
+  return (u.nodesCreated || 0) + (u.relationshipsCreated || 0) + (u.propertiesSet || 0);
+}
+
+/**
+ * Materialize the providers and MERGE them into Neo4j idempotently.
+ *
+ * @param {object} options
+ * @param {object} options.driver          neo4j driver (or the injected fake)
+ * @param {string} [options.database]
+ * @param {object[]} [options.providers]   #317 providers to read (or pass graph)
+ * @param {{nodes,edges}} [options.graph]  a pre-materialized graph (skips readers)
+ * @param {boolean} [options.force=false]  re-run MERGEs even if the digest matches
+ * @returns {Promise<{ writes:number, unchanged:boolean, digest:string, nodes:number, edges:number, snapshot:object, errors:object[] }>}
+ */
+export async function syncToNeo4j(options = {}) {
+  const { driver, database, force = false } = options;
+  let errors = [];
+  let graph = options.graph;
+  if (!graph) {
+    const mat = await materializeGraph(options.providers || []);
+    graph = { nodes: mat.nodes, edges: mat.edges };
+    errors = mat.errors;
+  }
+
+  const session = driver.session(database ? { database } : undefined);
+  try {
+    const priorDigest = await readPriorDigest(session);
+    const plan = planSync(graph, priorDigest, { force });
+
+    if (plan.unchanged && !force) {
+      return {
+        writes: 0,
+        unchanged: true,
+        digest: plan.digest,
+        nodes: graph.nodes.length,
+        edges: graph.edges.length,
+        snapshot: { digest: plan.digest },
+        errors,
+      };
+    }
+
+    let writes = 0;
+    for (const stmt of plan.statements) {
+      const res = await session.run(stmt.cypher, stmt.params);
+      writes += sumWrites(res.summary.counters);
+    }
+
+    const syncedAt = new Date().toISOString();
+    const snapRes = await session.run(
+      `MERGE (s:${SNAPSHOT_LABEL} {id:$id}) WITH s, $digest AS d WHERE coalesce(s.digest,'') <> d SET s.digest = d, s.synced_at = $syncedAt, s.node_count = $nc, s.edge_count = $ec`,
+      { id: SNAPSHOT_ID, digest: plan.digest, syncedAt, nc: graph.nodes.length, ec: graph.edges.length },
+    );
+    writes += sumWrites(snapRes.summary.counters);
+
+    return {
+      writes,
+      unchanged: plan.unchanged,
+      digest: plan.digest,
+      nodes: graph.nodes.length,
+      edges: graph.edges.length,
+      snapshot: { digest: plan.digest, synced_at: syncedAt },
+      errors,
+    };
+  } finally {
+    await session.close();
+  }
+}