@kontourai/flow-agents 2.4.0 → 3.0.0

package/schemas/knowledge/edge.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/edge.schema.json",
+  "title": "Knowledge Graph Edge",
+  "description": "A typed, directed edge between two nodes. The edge-type vocabulary is CLOSED (unlike node types): supersedes, merged-into, blocks, evidence-of, mentions, relates. Every edge carries provenance. The `to` endpoint MAY reference a node that is not present in the graph (an external or dangling reference); `resolved` records whether the provider expects the target to resolve, which the dependency-link-integrity health verb uses to separate deliberate external refs from broken links.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "from", "to", "provenance"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable identifier for the edge."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["supersedes", "merged-into", "blocks", "evidence-of", "mentions", "relates"],
+      "description": "supersedes: from replaces to. merged-into: from was folded into to. blocks: from must complete before to. evidence-of: from is provenance/evidence for to. mentions: from references to in prose. relates: general undirected-ish association."
+    },
+    "from": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Source node id."
+    },
+    "to": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Target node id. MAY be a node id not present in the graph when `resolved` is false (external ref)."
+    },
+    "resolved": {
+      "type": "boolean",
+      "description": "true (default when omitted) means the provider expects `to` to resolve to a node in the same graph; a missing target is then a broken link. false means `to` is a deliberate external reference (e.g. evidence-of a PR outside the store) and MUST NOT be flagged as broken."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Provider-specific structured fields for the edge."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string" },
+        "retrieved_at": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/knowledge/health-report.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/health-report.schema.json",
+  "title": "Knowledge Health Report",
+  "description": "The schema-valid output of a provider-agnostic health verb (duplicate detection, dependency-link integrity). The same report shape is produced regardless of which provider supplied the graph, which is what lets one health command run identically over vault, git-repo, and work-item.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "check", "provider", "generated_at", "summary", "findings"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "check": {
+      "type": "string",
+      "enum": ["duplicate-detection", "dependency-link-integrity"],
+      "description": "Which health verb produced the report."
+    },
+    "provider": { "type": "string", "minLength": 1, "description": "Provider id the graph was read from." },
+    "generated_at": { "type": "string", "minLength": 1 },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes_examined", "edges_examined", "finding_count"],
+      "properties": {
+        "nodes_examined": { "type": "integer" },
+        "edges_examined": { "type": "integer" },
+        "finding_count": { "type": "integer" }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "severity", "message", "evidence"],
+        "properties": {
+          "kind": { "type": "string", "minLength": 1 },
+          "severity": { "type": "string", "enum": ["info", "warning", "error"] },
+          "node_ids": { "type": "array", "items": { "type": "string" } },
+          "edge_ids": { "type": "array", "items": { "type": "string" } },
+          "message": { "type": "string", "minLength": 1 },
+          "evidence": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/schemas/knowledge/node.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/node.schema.json",
+  "title": "Knowledge Graph Node",
+  "description": "A typed node in the Knowledge Kit graph model. type is EXTENSIBLE: the recommended core vocabulary is note, decision, issue, session, person, but providers MAY emit additional types. Every node carries provenance so any assertion can be traced back to the store it came from.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "title", "provenance"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable identifier, unique within a single readGraph result."
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Node type. Recommended core vocabulary: note, decision, issue, session, person. Extensible — unknown types MUST NOT be rejected."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title used for display and duplicate detection."
+    },
+    "body": {
+      "type": "string",
+      "description": "Primary content. Format is provider/type-specific."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Provider-specific structured fields (e.g. issue state/labels, decision status, note category/tags)."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "description": "Provider id that produced this element (e.g. markdown-vault, git-repo, work-item)." },
+        "source": { "type": "string", "minLength": 1, "description": "The concrete origin: a file path, an issue ref, or a URL." },
+        "locator": { "type": "string", "description": "Optional finer locator within the source (line, anchor, frontmatter field)." },
+        "retrieved_at": { "type": "string", "minLength": 1, "description": "ISO-8601 timestamp the element was read." },
+        "agent": { "type": "string", "description": "Optional agent/process id that performed the read." }
+      }
+    }
+  }
+}

package/schemas/knowledge/proposal.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/proposal.schema.json",
+  "title": "Knowledge Store Write Proposal",
+  "description": "The ONLY write artifact a knowledge store provider may emit. Providers over human-curated stores are proposals-only: proposeWrite() never mutates the store and can only ever return a Proposal whose status is the const \"proposed\". Enactment happens downstream (a human edit, the decision-registry promote step, or a gh comment/label the operator files) — never inside the provider. The `rendered` field carries the provider-native form the enactor would apply (decision-registry topic frontmatter for git-repo; an issue comment/label body for work-item; a vault note with frontmatter+wikilinks for markdown-vault).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "provider", "kind", "target", "status", "provenance"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "provider": { "type": "string", "minLength": 1 },
+    "kind": {
+      "type": "string",
+      "enum": ["create-node", "update-node", "add-edge", "comment", "label", "decision-topic"],
+      "description": "The shape of the proposed change."
+    },
+    "target": {
+      "type": "object",
+      "description": "Where the change would land if enacted (file path, issue number, store id). Descriptive only — the provider does not touch it."
+    },
+    "payload": {
+      "type": "object",
+      "description": "The structured node/edge/field the proposal would introduce."
+    },
+    "rendered": {
+      "type": "string",
+      "description": "The provider-native rendered form an enactor would apply (topic-file frontmatter, gh comment body, vault note)."
+    },
+    "status": {
+      "const": "proposed",
+      "description": "Always the literal \"proposed\". A provider can NEVER return an applied proposal — this const is the structural expression of proposals-only discipline."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Why the change is proposed."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string" },
+        "retrieved_at": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string" }
+      }
+    }
+  }
+}