@kontourai/flow-agents 3.0.0 → 3.1.0

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

@@ -0,0 +1,190 @@
+/**
+ * Cypher for the neo4j knowledge-store provider.
+ *
+ * Two responsibilities:
+ *   1. The label/relationship mapping between the storage-independent graph model
+ *      (contract node `type` / edge `type`) and Neo4j's labelled property graph,
+ *      plus the read/merge statements the provider and sync command issue.
+ *   2. The five CANONICAL health/analysis queries from the #318 spike
+ *      (docs/spikes/graph-provider-2026-07.md §3), written in the Neo4j dialect.
+ *      The spike found ~80% of Cypher portable and isolated the three divergent
+ *      areas (existence predicates, string/list stdlib incl. 0- vs 1-indexed
+ *      substring, shortest-path/path-projection). These strings are the Neo4j
+ *      spelling; graph-queries.js is the portable JS spelling used in degraded
+ *      mode. The live integration test asserts the two agree.
+ *
+ * Nodes are stored one Neo4j label per contract type (Issue, Decision, Note,
+ * Session, Person, …) with a flat property bag; nested `attributes`/`provenance`
+ * are serialised to `*_json` strings (Neo4j properties cannot nest) and a few
+ * scalars (`state`, `status`) are promoted for queryability, matching the
+ * property catalogue the spike's Neo4j Browser panel showed.
+ *
+ * @module providers/neo4j/cypher
+ */
+
+/** Sanitise a contract node type into a Neo4j label (PascalCase, alnum only). */
+export function typeToLabel(type) {
+  const clean = String(type || "node").replace(/[^A-Za-z0-9]+/g, " ").trim();
+  if (!clean) return "Node";
+  return clean
+    .split(/\s+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+/** Sanitise a closed-vocabulary edge type into a Neo4j relationship type. */
+export function edgeTypeToRel(type) {
+  return String(type || "relates").toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+
+/** Reserved label for the sync snapshot metadata node (never part of the graph). */
+export const SNAPSHOT_LABEL = "_KGSnapshot";
+export const SNAPSHOT_ID = "current";
+
+/** Serialise a contract node into a flat Neo4j property bag. */
+export function nodeToProps(n, hash) {
+  const props = {
+    id: n.id,
+    type: n.type,
+    title: n.title,
+    body: n.body || "",
+    attributes_json: JSON.stringify(n.attributes || {}),
+    provenance_json: JSON.stringify(n.provenance || {}),
+    _kg_hash: hash,
+  };
+  // Promote a few queryable scalars (matches the spike's property catalogue).
+  const attrs = n.attributes || {};
+  if (attrs.state != null) props.state = String(attrs.state);
+  if (attrs.status != null) props.status = String(attrs.status);
+  if (attrs.registry_status != null) props.status = String(attrs.registry_status);
+  return props;
+}
+
+/** Rebuild a contract node from a Neo4j property bag. */
+export function propsToNode(props) {
+  const n = {
+    id: props.id,
+    type: props.type,
+    title: props.title,
+    provenance: safeParse(props.provenance_json, {}),
+  };
+  if (props.body) n.body = props.body;
+  const attrs = safeParse(props.attributes_json, {});
+  if (attrs && Object.keys(attrs).length) n.attributes = attrs;
+  return n;
+}
+
+/** Serialise a contract edge into a flat Neo4j property bag. */
+export function edgeToProps(e, hash) {
+  const props = {
+    id: e.id,
+    type: e.type,
+    from: e.from,
+    to: e.to,
+    resolved: e.resolved === false ? false : true,
+    attributes_json: JSON.stringify(e.attributes || {}),
+    provenance_json: JSON.stringify(e.provenance || {}),
+    _kg_hash: hash,
+  };
+  return props;
+}
+
+/** Rebuild a contract edge from a Neo4j relationship property bag. */
+export function propsToEdge(props) {
+  const e = {
+    id: props.id,
+    type: props.type,
+    from: props.from,
+    to: props.to,
+    provenance: safeParse(props.provenance_json, {}),
+  };
+  if (props.resolved === false) e.resolved = false;
+  const attrs = safeParse(props.attributes_json, {});
+  if (attrs && Object.keys(attrs).length) e.attributes = attrs;
+  return e;
+}
+
+function safeParse(s, fallback) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return fallback;
+  }
+}
+
+// --- fixed read statements ------------------------------------------------
+
+/** All graph nodes (excludes the snapshot metadata node). */
+export const READ_NODES_CYPHER = `MATCH (n) WHERE NOT n:${SNAPSHOT_LABEL} RETURN properties(n) AS props`;
+
+/** All graph relationships as flat property bags. */
+export const READ_EDGES_CYPHER = `MATCH ()-[r]->() RETURN properties(r) AS props`;
+
+/** The recorded sync snapshot (digest + timestamp), or null. */
+export const READ_SNAPSHOT_CYPHER = `MATCH (s:${SNAPSHOT_LABEL} {id:$id}) RETURN properties(s) AS props`;
+
+// --- canonical queries (Neo4j dialect, from the spike) --------------------
+
+/**
+ * The five canonical queries as Neo4j Cypher. `blocks` is stored from→to
+ * ("from must complete before to"), so a node's transitive blockers are reached
+ * by following INCOMING :BLOCKS. Placeholders are $-parameters (never string
+ * interpolation — the spike's escaping lesson).
+ */
+export const CANONICAL_CYPHER = Object.freeze({
+  // Q1 — transitive blocker closure (spike: variable-length *1..N, portable).
+  transitiveBlockers: `MATCH (b:Issue)-[:BLOCKS*1..$maxDepth]->(x:Issue {id:$rootId})
+RETURN DISTINCT b.id AS id, b.state AS state ORDER BY b.id`,
+
+  // Q2 — contradiction candidates: decisions sharing a subject with divergent
+  // status (the ADR-0007 numbering-collision failure mode).
+  contradictionCandidates: `MATCH (a:Decision),(b:Decision)
+WHERE a.id < b.id AND a.title = b.title AND coalesce(a.status,'') <> coalesce(b.status,'')
+RETURN a.id AS a_id, b.id AS b_id, a.status AS a_status, b.status AS b_status, a.title AS title`,
+
+  // Q3 — orphans, node-type aware (spike Q3: leaf types are source-only; the
+  // meaningful query is issues/decisions with no inbound edge).
+  orphans: `MATCH (n) WHERE NOT n:${SNAPSHOT_LABEL} AND NOT ( ()-->(n) )
+AND NOT n:Session AND NOT n:Pr AND NOT n:Learning
+RETURN labels(n)[0] AS label, n.id AS id ORDER BY id`,
+
+  // Q4 — duplicate candidates WITH 5-char-prefix stemming (spike Q4: exact
+  // tokens missed traverse#14~#8; substring() is 0-indexed in Neo4j).
+  duplicateStemmed: `MATCH (a),(b) WHERE a.id < b.id AND labels(a)[0] = labels(b)[0]
+WITH a, b,
+  [w IN split(toLower(a.title),' ') WHERE size(w)>=5 | substring(w,0,5)] AS sa,
+  [w IN split(toLower(b.title),' ') WHERE size(w)>=5 | substring(w,0,5)] AS sb
+WITH a, b, sa, sb, size([w IN sa WHERE w IN sb]) AS inter
+WHERE inter > 0 AND toFloat(inter)/size(sa + [w IN sb WHERE NOT w IN sa]) >= $threshold
+RETURN a.id AS a_id, b.id AS b_id, a.title AS a_title, b.title AS b_title`,
+
+  // Q5 — shortest path between two decisions (spike Q5: shortestPath() +
+  // list-comprehension projection is the Neo4j spelling).
+  shortestPath: `MATCH p=shortestPath((a {id:$fromId})-[*..$maxDepth]-(b {id:$toId}))
+RETURN [n IN nodes(p) | n.id] AS path, length(p) AS length`,
+});
+
+/**
+ * The spike's dialect note, kept with the queries so a future Kuzu/other-engine
+ * provider has the divergence map: existence predicates, string/list stdlib
+ * (incl. 0- vs 1-indexed substring), and shortest-path/path-projection spelling.
+ */
+export const DIALECT_NOTES = Object.freeze({
+  engine: "neo4j-community-5",
+  divergent_areas: ["existence-predicates", "string-list-stdlib", "shortest-path-projection"],
+  substring_indexing: "0-based",
+});
+
+/**
+ * Neo4j forbids a parameter in a variable-length bound (`*1..$maxDepth`). Bounds
+ * must be literals, so we validate maxDepth is a small positive integer and
+ * interpolate it — the ONLY interpolation in this module; every value stays a
+ * $-parameter (the spike's parameterise-don't-escape lesson).
+ */
+export function renderBounds(cypher, maxDepth) {
+  const n = Number(maxDepth);
+  if (!Number.isInteger(n) || n < 1 || n > 100) {
+    throw new Error(`renderBounds: maxDepth must be an integer in [1,100], got ${maxDepth}`);
+  }
+  return cypher.replace(/\$maxDepth/g, String(n));
+}

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