@kontourai/flow-agents 2.4.0 → 3.1.0

package/kits/knowledge/providers/lib/schema-validate.js

@@ -0,0 +1,119 @@
+/**
+ * Minimal, dependency-free JSON-Schema validator.
+ *
+ * Supports exactly the draft-07 subset used by the Knowledge Kit graph schemas
+ * (schemas/knowledge/*.schema.json): type, required, properties,
+ * additionalProperties:false, enum, const, items, minLength, minItems, integer,
+ * and local `$ref` into `#/$defs/*`. It is intentionally NOT a general validator
+ * — it exists so health reports and conformance tests can assert schema validity
+ * without pulling an external dependency (the same zero-dep discipline the
+ * decision-registry validator follows).
+ *
+ * @module providers/lib/schema-validate
+ */
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function matchesType(value, type) {
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+  if (type === "number") return typeof value === "number";
+  if (type === "object") return typeOf(value) === "object";
+  if (type === "array") return Array.isArray(value);
+  return typeOf(value) === type;
+}
+
+function resolveRef(ref, root) {
+  if (!ref.startsWith("#/")) throw new Error(`Unsupported $ref (only local #/ refs): ${ref}`);
+  const parts = ref.slice(2).split("/");
+  let node = root;
+  for (const part of parts) {
+    node = node && node[part];
+  }
+  if (!node) throw new Error(`Unresolved $ref: ${ref}`);
+  return node;
+}
+
+function validateNode(value, schema, root, pathStr, errors) {
+  if (schema.$ref) {
+    return validateNode(value, resolveRef(schema.$ref, root), root, pathStr, errors);
+  }
+
+  if ("const" in schema) {
+    if (value !== schema.const) {
+      errors.push(`${pathStr}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+    }
+  }
+
+  if (schema.enum) {
+    if (!schema.enum.includes(value)) {
+      errors.push(`${pathStr}: value ${JSON.stringify(value)} not in enum ${JSON.stringify(schema.enum)}`);
+    }
+  }
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => matchesType(value, t))) {
+      errors.push(`${pathStr}: expected type ${types.join("|")}, got ${typeOf(value)}`);
+      return; // further checks assume the type held
+    }
+  }
+
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+      errors.push(`${pathStr}: string shorter than minLength ${schema.minLength}`);
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+      errors.push(`${pathStr}: array shorter than minItems ${schema.minItems}`);
+    }
+    if (schema.items) {
+      value.forEach((item, i) => validateNode(item, schema.items, root, `${pathStr}[${i}]`, errors));
+    }
+  }
+
+  if (typeOf(value) === "object") {
+    const props = schema.properties || {};
+    for (const req of schema.required || []) {
+      if (!(req in value)) errors.push(`${pathStr}: missing required property '${req}'`);
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in props)) errors.push(`${pathStr}: unexpected property '${key}'`);
+      }
+    }
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (key in value) {
+        validateNode(value[key], propSchema, root, `${pathStr}/${key}`, errors);
+      }
+    }
+  }
+}
+
+/**
+ * Validate `value` against `schema`.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validate(value, schema) {
+  const errors = [];
+  validateNode(value, schema, schema, "$", errors);
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Assert validity, throwing a descriptive error when invalid. Handy in tests.
+ */
+export function assertValid(value, schema, label = "value") {
+  const { valid, errors } = validate(value, schema);
+  if (!valid) {
+    const err = new Error(`${label} failed schema validation:\n  ${errors.join("\n  ")}`);
+    err.code = "SCHEMA_INVALID";
+    err.errors = errors;
+    throw err;
+  }
+}

package/kits/knowledge/providers/markdown-vault/index.js

@@ -0,0 +1,169 @@
+/**
+ * markdown-vault knowledge-store provider.
+ *
+ * Adapts the existing Knowledge Kit store (the markdown-vault behaviour:
+ * markdown files + YAML frontmatter + [[wikilinks]] + a JSON graph index) to
+ * the knowledge-store PROVIDER contract (typed nodes/edges/provenance). It is a
+ * thin READ + PROPOSE wrapper over an existing store adapter instance — it does
+ * NOT reimplement or modify the adapter, so existing Knowledge Kit skills are
+ * unaffected. Wikilinks/frontmatter remain the native form; proposeWrite renders
+ * a new note in exactly that form for a human to file.
+ *
+ * @module providers/markdown-vault
+ */
+
+import { node, edge, proposal, provenance } from "../lib/model.js";
+import DefaultKnowledgeStore from "../../adapters/default-store/index.js";
+
+const PROVIDER_ID = "markdown-vault";
+
+/** Vault record type -> graph node type. Extensible: unknowns fall back to note. */
+function nodeTypeFor(recordType) {
+  return recordType === "person" ? "person" : "note";
+}
+
+/** Vault link kind -> closed graph edge type. */
+function edgeTypeFor(linkKind) {
+  switch (linkKind) {
+    case "supersedes":
+    case "refines":
+      return "supersedes";
+    case "source":
+    case "example":
+      return "evidence-of";
+    case "appears-in":
+    case "person":
+      return "mentions";
+    case "proposes":
+    case "related":
+    default:
+      return "relates";
+  }
+}
+
+const ALL_RECORD_TYPES = ["raw", "compiled", "concept", "snapshot", "person"];
+
+export class MarkdownVaultProvider {
+  constructor({ store, storeRoot, agent } = {}) {
+    if (!store && !storeRoot) {
+      throw new Error("MarkdownVaultProvider requires { store } or { storeRoot }");
+    }
+    this.store = store || new DefaultKnowledgeStore({ storeRoot });
+    this.storeRoot = storeRoot || "(injected store)";
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["note", "person"],
+      edge_types: ["supersedes", "evidence-of", "mentions", "relates"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["create-node"],
+      source_of_truth: "human-curated markdown vault",
+    };
+  }
+
+  async _allRecords() {
+    const out = [];
+    for (const t of ALL_RECORD_TYPES) {
+      const recs = await this.store.listByType(t, { includeRetired: true });
+      for (const r of recs) out.push(r);
+    }
+    return out;
+  }
+
+  async readNodes(options = {}) {
+    const records = await this._allRecords();
+    const nodes = records.map((r) => {
+      const attributes = { record_type: r.type };
+      if (r.category) attributes.category = r.category;
+      if (r.status) attributes.status = r.status;
+      if (Array.isArray(r.tags) && r.tags.length) attributes.tags = r.tags;
+      return node({
+        id: r.id,
+        type: nodeTypeFor(r.type),
+        title: r.title,
+        body: typeof r.body === "string" ? r.body : "",
+        attributes,
+        provenance: provenance({
+          provider: PROVIDER_ID,
+          source: `${this.storeRoot}#${r.id}`,
+          locator: r.type,
+          agent: this.agent,
+        }),
+      });
+    });
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    const records = await this._allRecords();
+    const edges = [];
+    for (const r of records) {
+      const links = await this.store.getLinks(r.id);
+      for (const l of links.forward || []) {
+        edges.push(
+          edge({
+            id: `${r.id}--${l.kind}--${l.target_id}`,
+            type: edgeTypeFor(l.kind),
+            from: r.id,
+            to: l.target_id,
+            attributes: { vault_link_kind: l.kind },
+            provenance: provenance({
+              provider: PROVIDER_ID,
+              source: `${this.storeRoot}#${r.id}`,
+              locator: `links.${l.kind}`,
+              agent: this.agent,
+            }),
+          }),
+        );
+      }
+    }
+    return edges;
+  }
+
+  async queryByType(type) {
+    return this.readNodes({ type });
+  }
+
+  async readGraph() {
+    const [nodes, edges] = await Promise.all([this.readNodes(), this.readEdges()]);
+    return { nodes, edges };
+  }
+
+  /**
+   * Propose a new vault note. Renders the native markdown-vault form
+   * (frontmatter + [[wikilinks]]) WITHOUT touching the store — proposals only.
+   */
+  async proposeWrite(intent = {}) {
+    const { title, body = "", category = "inbox", tags = [], links = [] } = intent;
+    if (!title) throw new Error("markdown-vault proposeWrite requires intent.title");
+    const wikilinks = links.map((l) => `[[${l.target_id}${l.label ? `|${l.label}` : ""}]]`).join(" ");
+    const fm = [
+      "---",
+      "type: compiled",
+      `title: ${title}`,
+      `category: ${category}`,
+      tags.length ? `tags: [${tags.join(", ")}]` : "tags: []",
+      "---",
+      "",
+      body,
+      wikilinks ? `\n${wikilinks}` : "",
+    ].join("\n");
+    return proposal({
+      provider: PROVIDER_ID,
+      kind: "create-node",
+      target: { store_root: this.storeRoot, category },
+      payload: { type: "note", title, body, category, tags, links },
+      rendered: fm,
+      rationale: intent.rationale || "Proposed vault note (file it via the Knowledge Kit ingest/compile flow).",
+      provenance: provenance({ provider: PROVIDER_ID, source: this.storeRoot, agent: this.agent }),
+    });
+  }
+}
+
+export default MarkdownVaultProvider;

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

@@ -0,0 +1,121 @@
+/**
+ * Connection + selection for the neo4j knowledge-store provider.
+ *
+ * Credentials are resolved BY REFERENCE, never hardcoded: the standard
+ * neo4j-driver environment variables NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD.
+ * (This repo does not yet consume @kontourai/datum — PR #365's model-routing
+ * adoption stayed config-file based — so we follow the existing env-reference
+ * precedent rather than inventing a datum coupling. If/when datum lands, resolve
+ * these three names through it without touching call sites.)
+ *
+ * The driver is a LAZY, OPTIONAL dependency: neo4j-driver is an
+ * optionalDependency, imported on first use inside a try/catch. A missing module
+ * OR an unreachable server both degrade to the file providers (AC4) — the graph
+ * is never a hard dependency of any repo or workflow.
+ *
+ * @module providers/neo4j/connection
+ */
+
+/**
+ * Resolve connection config by reference. Returns { uri, user, password,
+ * database } or null when NEO4J_URI is unset (the "no graph configured" signal).
+ * @param {object} [env=process.env]
+ */
+export function resolveNeo4jConfig(env = process.env) {
+  const uri = env.NEO4J_URI;
+  if (!uri) return null;
+  return {
+    uri,
+    user: env.NEO4J_USER || "neo4j",
+    password: env.NEO4J_PASSWORD || "",
+    database: env.NEO4J_DATABASE || "neo4j",
+  };
+}
+
+/**
+ * Lazily import neo4j-driver and construct a driver. Returns null if the module
+ * is not installed (optional dependency absent) — the caller degrades.
+ * @param {object} config from resolveNeo4jConfig
+ */
+export async function createDriver(config) {
+  if (!config) return null;
+  let neo4j;
+  try {
+    neo4j = (await import("neo4j-driver")).default;
+  } catch {
+    return null; // optional dependency not installed -> degrade
+  }
+  const driver = neo4j.driver(config.uri, neo4j.auth.basic(config.user, config.password));
+  // Real (non-fake) driver: the live Cypher analytics backend is available.
+  driver.supportsCypherAnalytics = true;
+  driver._kgDatabase = config.database;
+  return driver;
+}
+
+/**
+ * Probe whether a Neo4j server is reachable with these credentials. Never
+ * throws — returns false on any failure. Used by selectKnowledgeProvider so a
+ * down/absent server degrades cleanly instead of erroring.
+ * @param {object} driver
+ */
+export async function isReachable(driver, { timeoutMs = 4000 } = {}) {
+  if (!driver) return false;
+  try {
+    await withTimeout(driver.verifyConnectivity(), timeoutMs);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), ms).unref?.()),
+  ]);
+}
+
+/**
+ * Select the knowledge provider set. The default is the file providers; the
+ * neo4j graph is an OPT-IN personal default. Selection is config-driven:
+ * `preference` (from repo/user config or KNOWLEDGE_PROVIDER env) chooses neo4j;
+ * anything else, or an unreachable/absent Neo4j, falls back to the file
+ * providers with a single clear message (AC4).
+ *
+ * @param {object} options
+ * @param {"neo4j"|"file"} [options.preference] explicit preference (default from env)
+ * @param {() => object[]|Promise<object[]>} options.fileProviders factory for the file provider set
+ * @param {(cfg:object)=>Promise<object>} [options.neo4jFactory] builds the neo4j provider (driver injected)
+ * @param {object} [options.env=process.env]
+ * @param {(msg:string)=>void} [options.log] one-line status sink (default console.error)
+ * @returns {Promise<{ provider:string, providers:object[], graph:object|null, message:string }>}
+ */
+export async function selectKnowledgeProvider(options = {}) {
+  const env = options.env || process.env;
+  const log = options.log || ((m) => console.error(m));
+  const preference = options.preference || env.KNOWLEDGE_PROVIDER || "file";
+
+  const fallback = async (message) => {
+    log(message);
+    return { provider: "file", providers: await options.fileProviders(), graph: null, message };
+  };
+
+  if (preference !== "neo4j") {
+    return { provider: "file", providers: await options.fileProviders(), graph: null, message: "" };
+  }
+
+  const config = resolveNeo4jConfig(env);
+  if (!config) {
+    return fallback("knowledge: neo4j selected but NEO4J_URI is unset — using file providers.");
+  }
+  const driver = options.driver || (await createDriver(config));
+  if (!driver) {
+    return fallback("knowledge: neo4j-driver not installed — using file providers (run `npm install neo4j-driver`).");
+  }
+  if (!(await isReachable(driver))) {
+    await driver.close?.();
+    return fallback(`knowledge: no Neo4j reachable at ${config.uri} — using file providers.`);
+  }
+  const provider = await options.neo4jFactory({ driver, database: config.database });
+  return { provider: "neo4j", providers: [provider], graph: provider, message: `knowledge: neo4j provider selected (${config.uri}).` };
+}

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