@kontourai/flow-agents 2.4.0 → 3.1.0

package/kits/knowledge/providers/neo4j/fake-driver.js

@@ -0,0 +1,123 @@
+/**
+ * In-memory injected driver mock for the neo4j provider.
+ *
+ * Implements exactly the fixed statements the provider and sync command issue
+ * (node/edge/snapshot reads; hash-guarded MERGE writes) over an in-process
+ * property-bag graph, returning honest neo4j-driver-shaped results and update
+ * counters. This is the "injected driver mock" the CI proof relies on (issue
+ * #327): the read side conforms and the sync idempotency counters (writes>0 then
+ * writes=0) are provable with no Docker present.
+ *
+ * It deliberately does NOT interpret the analytic canonical queries — it reports
+ * supportsCypherAnalytics=false, so the provider uses the portable JS backend
+ * for those. The live driver interprets them; integration.test.js asserts parity.
+ *
+ * @module providers/neo4j/fake-driver
+ */
+
+import {
+  READ_NODES_CYPHER,
+  READ_EDGES_CYPHER,
+  READ_SNAPSHOT_CYPHER,
+} from "./cypher.js";
+
+function record(map) {
+  return { get: (key) => map[key] };
+}
+
+function counters(updates) {
+  return { summary: { counters: { updates: () => updates } } };
+}
+
+export function makeFakeDriver() {
+  const nodes = new Map(); // id -> props (incl. _kg_label, _kg_hash)
+  const rels = new Map(); // id -> props (incl. _kg_rel, _kg_hash)
+  let snapshot = null;
+
+  function run(cypher, params = {}) {
+    // --- reads ---
+    if (cypher === READ_NODES_CYPHER) {
+      return Promise.resolve({ records: [...nodes.values()].map((p) => record({ props: strip(p) })) });
+    }
+    if (cypher === READ_EDGES_CYPHER) {
+      return Promise.resolve({ records: [...rels.values()].map((p) => record({ props: strip(p) })) });
+    }
+    if (cypher === READ_SNAPSHOT_CYPHER) {
+      return Promise.resolve({ records: snapshot ? [record({ props: snapshot })] : [] });
+    }
+
+    // --- node MERGE ---
+    let m = cypher.match(/MERGE \(n:([A-Za-z0-9_]+) \{id:r\.id\}\)/);
+    if (m) {
+      let nodesCreated = 0;
+      let propertiesSet = 0;
+      for (const r of params.rows || []) {
+        const existing = nodes.get(r.id);
+        if (!existing) {
+          nodes.set(r.id, { ...r, _kg_label: m[1] });
+          nodesCreated++;
+          propertiesSet += Object.keys(r).length;
+        } else if (existing._kg_hash !== r._kg_hash) {
+          nodes.set(r.id, { ...existing, ...r, _kg_label: m[1] });
+          propertiesSet += Object.keys(r).length;
+        }
+      }
+      return Promise.resolve(counters({ nodesCreated, relationshipsCreated: 0, propertiesSet }));
+    }
+
+    // --- edge MERGE ---
+    m = cypher.match(/MERGE \(a\)-\[x:([A-Za-z0-9_]+) \{id:r\.id\}\]->\(b\)/);
+    if (m) {
+      let relationshipsCreated = 0;
+      let propertiesSet = 0;
+      for (const r of params.rows || []) {
+        if (!nodes.has(r.from) || !nodes.has(r.to)) continue; // MATCH endpoints failed
+        const existing = rels.get(r.id);
+        if (!existing) {
+          rels.set(r.id, { ...r, _kg_rel: m[1] });
+          relationshipsCreated++;
+          propertiesSet += Object.keys(r).length;
+        } else if (existing._kg_hash !== r._kg_hash) {
+          rels.set(r.id, { ...existing, ...r, _kg_rel: m[1] });
+          propertiesSet += Object.keys(r).length;
+        }
+      }
+      return Promise.resolve(counters({ nodesCreated: 0, relationshipsCreated, propertiesSet }));
+    }
+
+    // --- snapshot MERGE ---
+    if (/MERGE \(s:_KGSnapshot \{id:\$id\}\)/.test(cypher)) {
+      let nodesCreated = 0;
+      let propertiesSet = 0;
+      if (!snapshot) {
+        snapshot = { id: params.id, digest: params.digest, synced_at: params.syncedAt, node_count: params.nc, edge_count: params.ec };
+        nodesCreated = 1;
+        propertiesSet = 4;
+      } else if (snapshot.digest !== params.digest) {
+        snapshot = { ...snapshot, digest: params.digest, synced_at: params.syncedAt, node_count: params.nc, edge_count: params.ec };
+        propertiesSet = 4;
+      }
+      return Promise.resolve(counters({ nodesCreated, relationshipsCreated: 0, propertiesSet }));
+    }
+
+    throw new Error(`fake-driver: unhandled statement:\n${cypher}`);
+  }
+
+  function strip(p) {
+    // Return only the stored Neo4j properties (drop the fake's bookkeeping keys).
+    const { _kg_label, _kg_rel, ...rest } = p;
+    return rest;
+  }
+
+  const session = () => ({ run, close: () => Promise.resolve() });
+  return {
+    supportsCypherAnalytics: false,
+    __fake: true,
+    session,
+    verifyConnectivity: () => Promise.resolve(true),
+    close: () => Promise.resolve(),
+    _state: { nodes, rels, get snapshot() { return snapshot; } },
+  };
+}
+
+export default makeFakeDriver;

package/kits/knowledge/providers/neo4j/fixtures/spike-ground-truth.json

@@ -0,0 +1,29 @@
+{
+  "_comment": "Compact graph encoding the #318 spike's ground-truth cases for the five canonical queries (docs/spikes/graph-provider-2026-07.md). Not the full 200-node portfolio; the KEY findings each query proved. Used by both the JS backend (CI) and the live Cypher backend (integration) so AC3 asserts the same results in both.",
+  "nodes": [
+    { "id": "issue:310", "type": "issue", "title": "Decision registry shape", "attributes": { "state": "CLOSED" }, "provenance": { "provider": "work-item", "source": "fixture#310", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "issue:312", "type": "issue", "title": "Flow-agents build lane", "attributes": { "state": "OPEN" }, "provenance": { "provider": "work-item", "source": "fixture#312", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "issue:313", "type": "issue", "title": "Knowledge promote sub-flow", "attributes": { "state": "OPEN" }, "provenance": { "provider": "work-item", "source": "fixture#313", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "issue:317", "type": "issue", "title": "Knowledge store provider interface", "attributes": { "state": "OPEN" }, "provenance": { "provider": "work-item", "source": "fixture#317", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "issue:137", "type": "issue", "title": "Core vs domain boundary", "attributes": { "state": "OPEN" }, "provenance": { "provider": "work-item", "source": "fixture#137", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "issue:traverse-8", "type": "issue", "title": "Chunk extraction dedup", "attributes": { "state": "OPEN" }, "provenance": { "provider": "work-item", "source": "traverse#8", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "issue:traverse-14", "type": "issue", "title": "Chunking extractor deduplication", "attributes": { "state": "OPEN" }, "provenance": { "provider": "work-item", "source": "traverse#14", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "decision:adr-0007", "type": "decision", "title": "Flow Skill Kit Tool Boundary", "attributes": { "status": "Accepted" }, "provenance": { "provider": "git-repo", "source": "docs/adr/0007.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "decision:adr-0007b", "type": "decision", "title": "Flow Skill Kit Tool Boundary", "attributes": { "status": "" }, "provenance": { "provider": "git-repo", "source": "docs/adr/0007b.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "decision:adr-0011", "type": "decision", "title": "Trust reconcile and delivery", "attributes": { "status": "Accepted" }, "provenance": { "provider": "git-repo", "source": "docs/adr/0011.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "decision:adr-0021", "type": "decision", "title": "Assignment leases and takeover", "attributes": { "status": "Draft" }, "provenance": { "provider": "git-repo", "source": "docs/adr/0021.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "decision:orphan-adr", "type": "decision", "title": "Undiscoverable stale decision", "attributes": { "status": "Accepted" }, "provenance": { "provider": "git-repo", "source": "docs/adr/orphan.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "session:s1", "type": "session", "title": "Session 2026-07-02 sweep", "provenance": { "provider": "markdown-vault", "source": "archive#s1", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "learning:l1", "type": "learning", "title": "Improvement program note", "provenance": { "provider": "git-repo", "source": "docs/learnings/2026-07.md", "retrieved_at": "2026-07-03T05:14:42Z" } }
+  ],
+  "edges": [
+    { "id": "e1", "type": "blocks", "from": "issue:310", "to": "issue:312", "provenance": { "provider": "work-item", "source": "fixture#312", "locator": "metadata.blockers", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e2", "type": "blocks", "from": "issue:312", "to": "issue:313", "provenance": { "provider": "work-item", "source": "fixture#313", "locator": "metadata.blockers", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e3", "type": "mentions", "from": "decision:adr-0011", "to": "issue:137", "provenance": { "provider": "git-repo", "source": "docs/adr/0011.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e4", "type": "mentions", "from": "decision:adr-0021", "to": "issue:137", "provenance": { "provider": "git-repo", "source": "docs/adr/0021.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e5", "type": "evidence-of", "from": "session:s1", "to": "decision:adr-0011", "provenance": { "provider": "markdown-vault", "source": "archive#s1", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e6", "type": "evidence-of", "from": "session:s1", "to": "decision:adr-0021", "provenance": { "provider": "markdown-vault", "source": "archive#s1", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e7", "type": "mentions", "from": "learning:l1", "to": "decision:adr-0007", "provenance": { "provider": "git-repo", "source": "docs/learnings/2026-07.md", "retrieved_at": "2026-07-03T05:14:42Z" } },
+    { "id": "e8", "type": "mentions", "from": "learning:l1", "to": "decision:adr-0007b", "provenance": { "provider": "git-repo", "source": "docs/learnings/2026-07.md", "retrieved_at": "2026-07-03T05:14:42Z" } }
+  ]
+}

package/kits/knowledge/providers/neo4j/graph-queries.js

@@ -0,0 +1,210 @@
+/**
+ * Portable JS spelling of the five canonical spike queries, over a contract
+ * graph ({ nodes, edges }).
+ *
+ * The #318 spike proved "the value is the MODEL and the QUERIES, not either
+ * engine" — at portfolio scale an in-memory JS graph answers every canonical
+ * query in milliseconds. These functions are that spelling: they back the
+ * neo4j provider's query/health verbs when no live Neo4j is reachable (AC4
+ * graceful degradation to file providers), and they are the ground-truth oracle
+ * the live Cypher path is asserted against (AC3). Same answers, two backends —
+ * exactly the portability the spike's dialect-shim note calls for.
+ *
+ * @module providers/neo4j/graph-queries
+ */
+
+/** Tokenise a title into lowercased alnum tokens. */
+function tokens(title) {
+  return String(title || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * Stemmed token set: 5-char prefix of tokens of length >= 5 (the spike's Q4
+ * stemming — "chunk"/"chunking" -> "chunk", "extraction"/"extractor" -> "extra").
+ * Short tokens are dropped, matching the spike's `WHERE size(w)>=5`.
+ */
+function stemSet(title) {
+  return new Set(tokens(title).filter((w) => w.length >= 5).map((w) => w.slice(0, 5)));
+}
+
+/** Exact token set (what naive title matching sees — the spike's miss). */
+function exactSet(title) {
+  return new Set(tokens(title));
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter++;
+  const union = a.size + b.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+
+/**
+ * Q1 — transitive blocker closure. A `blocks` edge is from -> to ("from must
+ * complete before to"), so a node's transitive blockers are reached by walking
+ * INCOMING blocks edges. Returns blocker nodes (excluding the root) with state.
+ */
+export function transitiveBlockers(graph, { rootId, maxDepth = 10 } = {}) {
+  const edges = (graph.edges || []).filter((e) => e.type === "blocks");
+  const byId = new Map((graph.nodes || []).map((n) => [n.id, n]));
+  const incoming = new Map();
+  for (const e of edges) {
+    if (!incoming.has(e.to)) incoming.set(e.to, []);
+    incoming.get(e.to).push(e.from);
+  }
+  const seen = new Set();
+  let frontier = [rootId];
+  let depth = 0;
+  while (frontier.length && depth < maxDepth) {
+    const next = [];
+    for (const node of frontier) {
+      for (const from of incoming.get(node) || []) {
+        if (from === rootId || seen.has(from)) continue;
+        seen.add(from);
+        next.push(from);
+      }
+    }
+    frontier = next;
+    depth++;
+  }
+  return [...seen]
+    .sort()
+    .map((id) => ({ id, state: (byId.get(id)?.attributes || {}).state ?? null }));
+}
+
+/**
+ * Q2 — contradiction candidates: decision nodes that share a subject (stemmed
+ * title match) but carry divergent status. The ADR-0007 numbering-collision
+ * failure mode the spike caught red-handed.
+ */
+export function contradictionCandidates(graph, { threshold = 0.7 } = {}) {
+  const decisions = (graph.nodes || []).filter((n) => n.type === "decision");
+  const out = [];
+  for (let i = 0; i < decisions.length; i++) {
+    for (let j = i + 1; j < decisions.length; j++) {
+      const a = decisions[i];
+      const b = decisions[j];
+      const sim = jaccard(stemSet(a.title), stemSet(b.title));
+      if (sim < threshold) continue;
+      const sa = status(a);
+      const sb = status(b);
+      if (sa === sb) continue;
+      out.push({
+        a_id: a.id,
+        b_id: b.id,
+        a_status: sa,
+        b_status: sb,
+        title: a.title,
+        similarity: Number(sim.toFixed(4)),
+      });
+    }
+  }
+  return out.sort((x, y) => (x.a_id + x.b_id).localeCompare(y.a_id + y.b_id));
+}
+
+function status(n) {
+  const a = n.attributes || {};
+  return a.status ?? a.registry_status ?? "";
+}
+
+/**
+ * Q3 — orphans, node-type aware. Leaf/source-only types (session, pr, learning)
+ * originate edges by construction, so flagging them is noise (spike Q3 lesson).
+ * Meaningful orphans are non-leaf nodes with no inbound edge.
+ */
+export function orphans(graph, { excludeTypes = ["session", "pr", "learning"] } = {}) {
+  const exclude = new Set(excludeTypes);
+  const inbound = new Set((graph.edges || []).map((e) => e.to));
+  return (graph.nodes || [])
+    .filter((n) => !exclude.has(n.type) && !inbound.has(n.id))
+    .map((n) => ({ id: n.id, type: n.type, title: n.title }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Q4 — duplicate candidates WITH stemming. Same-type pairs whose STEMMED token
+ * sets cross the threshold. Exact-token Jaccard is reported alongside so callers
+ * (and the AC3 test) can see the spike's finding: exact tokens miss traverse#14,
+ * stemming catches it.
+ */
+export function duplicateCandidates(graph, { threshold = 0.7, crossType = false } = {}) {
+  const nodes = graph.nodes || [];
+  const out = [];
+  for (let i = 0; i < nodes.length; i++) {
+    for (let j = i + 1; j < nodes.length; j++) {
+      const a = nodes[i];
+      const b = nodes[j];
+      if (!crossType && a.type !== b.type) continue;
+      const stemmed = jaccard(stemSet(a.title), stemSet(b.title));
+      const exact = jaccard(exactSet(a.title), exactSet(b.title));
+      if (stemmed < threshold) continue;
+      out.push({
+        a_id: a.id,
+        b_id: b.id,
+        a_title: a.title,
+        b_title: b.title,
+        type: a.type,
+        stemmed_similarity: Number(stemmed.toFixed(4)),
+        exact_similarity: Number(exact.toFixed(4)),
+        caught_only_by_stemming: exact < threshold,
+      });
+    }
+  }
+  return out.sort((x, y) => y.stemmed_similarity - x.stemmed_similarity);
+}
+
+/**
+ * Q5 — shortest path between two nodes over the undirected edge set. Returns the
+ * node-id path and its length, or null if unreachable within maxDepth.
+ */
+export function shortestPath(graph, { fromId, toId, maxDepth = 8 } = {}) {
+  if (fromId === toId) return { path: [fromId], length: 0 };
+  const adj = new Map();
+  const add = (u, v) => {
+    if (!adj.has(u)) adj.set(u, new Set());
+    adj.get(u).add(v);
+  };
+  for (const e of graph.edges || []) {
+    add(e.from, e.to);
+    add(e.to, e.from);
+  }
+  const prev = new Map([[fromId, null]]);
+  let frontier = [fromId];
+  let depth = 0;
+  while (frontier.length && depth < maxDepth) {
+    const next = [];
+    for (const u of frontier) {
+      for (const v of adj.get(u) || []) {
+        if (prev.has(v)) continue;
+        prev.set(v, u);
+        if (v === toId) {
+          const path = [];
+          let cur = toId;
+          while (cur != null) {
+            path.unshift(cur);
+            cur = prev.get(cur);
+          }
+          return { path, length: path.length - 1 };
+        }
+        next.push(v);
+      }
+    }
+    frontier = next;
+    depth++;
+  }
+  return null;
+}
+
+/** Named registry of the five canonical query verbs (portable JS backend). */
+export const CANONICAL_QUERIES = Object.freeze({
+  transitiveBlockers,
+  contradictionCandidates,
+  orphans,
+  duplicateCandidates,
+  shortestPath,
+});

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";