@kontourai/flow-agents 3.0.0 → 3.1.0

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

@@ -0,0 +1,280 @@
+/**
+ * neo4j knowledge-store provider (opt-in personal default; file providers remain
+ * the portfolio default — issue #327).
+ *
+ * Implements the #317 read + proposals-only interface over Neo4j Community. The
+ * graph is a MATERIALIZED VIEW synced from the file/work-item providers (see
+ * sync.js) — the file stores stay the source of truth, and the write side is
+ * proposals-only so the graph never becomes an authority that bypasses the
+ * human-curated stores.
+ *
+ * Query/health verbs run Cypher-backed when a live Neo4j is present (the five
+ * canonical spike queries) and fall back to the portable JS spelling
+ * (graph-queries.js) otherwise — same answers, two backends (AC3/AC4).
+ *
+ * The driver is INJECTABLE: unit tests pass a fake driver (fake-driver.js) so
+ * the read side is conformance-tested with no Docker; live integration passes a
+ * real neo4j-driver. Absence of either degrades to file providers (AC4).
+ *
+ * @module providers/neo4j
+ */
+
+import { node as buildNode, edge as buildEdge, proposal, provenance } from "../lib/model.js";
+import { detectDuplicates, checkDependencyLinkIntegrity } from "../health/index.js";
+import {
+  READ_NODES_CYPHER,
+  READ_EDGES_CYPHER,
+  CANONICAL_CYPHER,
+  renderBounds,
+  propsToNode,
+  propsToEdge,
+} from "./cypher.js";
+import * as jsq from "./graph-queries.js";
+
+const PROVIDER_ID = "neo4j";
+
+/** Coerce a neo4j-driver Integer (or number) to a JS number. */
+function num(v) {
+  if (v == null) return null;
+  if (typeof v === "number") return v;
+  if (typeof v.toNumber === "function") return v.toNumber();
+  return Number(v);
+}
+
+export class Neo4jProvider {
+  /**
+   * @param {object} options
+   * @param {object} [options.driver]       neo4j driver or injected fake
+   * @param {string} [options.database]
+   * @param {{nodes,edges}} [options.sourceGraph] read directly from memory (degraded/test)
+   * @param {string} [options.agent]
+   */
+  constructor({ driver, database, sourceGraph, agent } = {}) {
+    if (!driver && !sourceGraph) {
+      throw new Error("Neo4jProvider requires { driver } or { sourceGraph }");
+    }
+    this.driver = driver;
+    this.database = database;
+    this.sourceGraph = sourceGraph;
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+    // Live Cypher analytics only when a real driver advertises support; the fake
+    // driver and the in-memory path use the portable JS backend.
+    this._cypherAnalytics = Boolean(driver && driver.supportsCypherAnalytics);
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["issue", "decision", "note", "session", "person"],
+      edge_types: ["blocks", "evidence-of", "supersedes", "merged-into", "mentions", "relates"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["create-node", "add-edge"],
+      source_of_truth: "file providers (vault, git-repo, work-item); the graph is a synced materialized view",
+    };
+  }
+
+  _session() {
+    return this.driver.session(this.database ? { database: this.database } : undefined);
+  }
+
+  async _run(cypher, params) {
+    const session = this._session();
+    try {
+      return await session.run(cypher, params);
+    } finally {
+      await session.close();
+    }
+  }
+
+
+  // The graph is a materialized VIEW: neo4j produced this read, but the element
+  // originated in a curated store. Stamp provider=neo4j (what the contract's
+  // provenance.provider means — "the provider that produced the element") while
+  // preserving the origin store in source + locator, so every fact stays
+  // traceable back to where it came from.
+  _viewProvenance(orig = {}) {
+    const originProvider = orig.provider && orig.provider !== PROVIDER_ID ? orig.provider : null;
+    const locatorBits = [];
+    if (originProvider) locatorBits.push(`origin:${originProvider}`);
+    if (orig.locator) locatorBits.push(orig.locator);
+    const prov = {
+      provider: PROVIDER_ID,
+      source: orig.source || "neo4j://materialized-view",
+      retrieved_at: orig.retrieved_at || new Date().toISOString(),
+    };
+    if (locatorBits.length) prov.locator = locatorBits.join("#");
+    if (this.agent) prov.agent = this.agent;
+    return prov;
+  }
+
+  async readNodes(options = {}) {
+    let nodes;
+    if (this.sourceGraph && !this.driver) {
+      nodes = (this.sourceGraph.nodes || []).map((n) => this._normalizeNode(n));
+    } else {
+      const res = await this._run(READ_NODES_CYPHER);
+      nodes = res.records.map((r) => { const n = propsToNode(r.get("props")); n.provenance = this._viewProvenance(n.provenance); return n; });
+    }
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    if (this.sourceGraph && !this.driver) {
+      return (this.sourceGraph.edges || []).map((e) => this._normalizeEdge(e));
+    }
+    const res = await this._run(READ_EDGES_CYPHER);
+    return res.records.map((r) => { const e = propsToEdge(r.get("props")); e.provenance = this._viewProvenance(e.provenance); return e; });
+  }
+
+  // Normalise an in-memory node/edge through the model constructors so the
+  // sourceGraph path emits the same schema-clean shape as the Cypher path.
+  _normalizeNode(n) {
+    return buildNode({
+      id: n.id,
+      type: n.type,
+      title: n.title,
+      body: n.body,
+      attributes: n.attributes,
+      provenance: this._viewProvenance(n.provenance || {}),
+    });
+  }
+
+  _normalizeEdge(e) {
+    return buildEdge({
+      id: e.id,
+      type: e.type,
+      from: e.from,
+      to: e.to,
+      resolved: e.resolved,
+      attributes: e.attributes,
+      provenance: this._viewProvenance(e.provenance || {}),
+    });
+  }
+
+  async queryByType(type) {
+    return this.readNodes({ type });
+  }
+
+  async readGraph() {
+    const [nodes, edges] = await Promise.all([this.readNodes(), this.readEdges()]);
+    return { nodes, edges };
+  }
+
+  /**
+   * Proposals-only write. The graph is a view: an intended change is rendered as
+   * the Cypher an enactor WOULD run, but proposeWrite never mutates the store,
+   * and the rationale is explicit that the real change must land in the source
+   * store and reach the graph via `sync` — the graph is never an authority that
+   * bypasses the curated stores.
+   */
+  async proposeWrite(intent = {}) {
+    const kind = intent.kind === "add-edge" ? "add-edge" : "create-node";
+    let rendered;
+    let payload;
+    if (kind === "add-edge") {
+      const { type = "relates", from, to } = intent;
+      if (!from || !to) throw new Error("neo4j proposeWrite add-edge requires intent.from and intent.to");
+      const rel = String(type).toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+      payload = { type, from, to };
+      rendered = `MATCH (a {id:$from}),(b {id:$to}) MERGE (a)-[:${rel}]->(b)  // proposal — enact upstream, then \`sync\``;
+    } else {
+      const { type = "note", title } = intent;
+      if (!title) throw new Error("neo4j proposeWrite create-node requires intent.title");
+      const label = String(type).charAt(0).toUpperCase() + String(type).slice(1);
+      payload = { type, title, body: intent.body || "" };
+      rendered = `MERGE (n:${label} {id:$id}) SET n.title=$title  // proposal — enact upstream, then \`sync\``;
+    }
+    return proposal({
+      provider: PROVIDER_ID,
+      kind,
+      target: { store: "neo4j (materialized view)" },
+      payload,
+      rendered,
+      rationale:
+        "Proposed graph change. The graph is a materialized VIEW: enact the change in the source store (vault / git-repo / work-item) and re-run `sync` — never write the graph directly as an authority.",
+      provenance: provenance({ provider: PROVIDER_ID, source: "neo4j://materialized-view", agent: this.agent }),
+    });
+  }
+
+  // --- canonical query / health verbs -------------------------------------
+
+  async transitiveBlockers(rootId, opts = {}) {
+    const maxDepth = opts.maxDepth || 10;
+    if (this._cypherAnalytics) {
+      const res = await this._run(renderBounds(CANONICAL_CYPHER.transitiveBlockers, maxDepth), { rootId });
+      return res.records.map((r) => ({ id: r.get("id"), state: r.get("state") ?? null }));
+    }
+    return jsq.transitiveBlockers(await this.readGraph(), { rootId, maxDepth });
+  }
+
+  async contradictionCandidates(opts = {}) {
+    if (this._cypherAnalytics) {
+      const res = await this._run(CANONICAL_CYPHER.contradictionCandidates, {});
+      return res.records.map((r) => ({
+        a_id: r.get("a_id"),
+        b_id: r.get("b_id"),
+        a_status: r.get("a_status"),
+        b_status: r.get("b_status"),
+        title: r.get("title"),
+      }));
+    }
+    return jsq.contradictionCandidates(await this.readGraph(), opts);
+  }
+
+  async orphans(opts = {}) {
+    if (this._cypherAnalytics) {
+      const res = await this._run(CANONICAL_CYPHER.orphans, {});
+      return res.records.map((r) => ({ id: r.get("id"), label: r.get("label") }));
+    }
+    return jsq.orphans(await this.readGraph(), opts);
+  }
+
+  async duplicateCandidates(opts = {}) {
+    const threshold = typeof opts.threshold === "number" ? opts.threshold : 0.7;
+    if (this._cypherAnalytics) {
+      const res = await this._run(CANONICAL_CYPHER.duplicateStemmed, { threshold });
+      return res.records.map((r) => ({
+        a_id: r.get("a_id"),
+        b_id: r.get("b_id"),
+        a_title: r.get("a_title"),
+        b_title: r.get("b_title"),
+      }));
+    }
+    return jsq.duplicateCandidates(await this.readGraph(), { ...opts, threshold });
+  }
+
+  async shortestPath(fromId, toId, opts = {}) {
+    const maxDepth = opts.maxDepth || 8;
+    if (this._cypherAnalytics) {
+      const res = await this._run(renderBounds(CANONICAL_CYPHER.shortestPath, maxDepth), { fromId, toId });
+      const rec = res.records[0];
+      if (!rec) return null;
+      return { path: rec.get("path"), length: num(rec.get("length")) };
+    }
+    return jsq.shortestPath(await this.readGraph(), { fromId, toId, maxDepth });
+  }
+
+  /** Provider-agnostic duplicate-detection health report (schema-valid). */
+  async detectDuplicates(opts = {}) {
+    return detectDuplicates(await this.readGraph(), { provider: PROVIDER_ID, ...opts });
+  }
+
+  /** Provider-agnostic dependency-link-integrity health report (schema-valid). */
+  async checkDependencyLinkIntegrity(opts = {}) {
+    return checkDependencyLinkIntegrity(await this.readGraph(), { provider: PROVIDER_ID, ...opts });
+  }
+}
+
+export default Neo4jProvider;
+export { syncToNeo4j, materializeGraph, planSync, computeDigest } from "./sync.js";
+export {
+  resolveNeo4jConfig,
+  createDriver,
+  isReachable,
+  selectKnowledgeProvider,
+} from "./connection.js";
+export { CANONICAL_QUERIES } from "./graph-queries.js";
+export { CANONICAL_CYPHER, DIALECT_NOTES } from "./cypher.js";

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");
+  });
+});