@kontourai/flow-agents 3.12.1 → 4.1.0

package/schemas/narrative-runtime-projection.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/narrative-runtime-projection.schema.json",
+  "title": "Flow Agents Grounded Runtime Projection",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "narrative_id", "provenance", "capture_completeness", "turns", "document_statements", "coverage"],
+  "$defs": {
+    "source_id": {
+      "type": "string",
+      "pattern": "^fa1:(telemetry|cmdlog|agent-event|delegation|trust-claim|trust-evidence|flow-state|flow-report|flow-transition|surface-explanation|transcript|file):(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*:(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*(?:#(?:0|[1-9][0-9]*))?$"
+    },
+    "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "known_gap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["class", "ref"],
+      "properties": {
+        "class": { "type": "string", "enum": ["mcp_non_native_tools", "actor_attribution_conflation", "cross_session_event_contamination"] },
+        "ref": { "type": "string", "minLength": 1 },
+        "note": { "type": "string", "minLength": 1 }
+      }
+    },
+    "capture_completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channels", "known_gaps"],
+      "properties": {
+        "channels": { "type": "object", "additionalProperties": { "type": "string", "enum": ["active", "inactive", "unknown"] } },
+        "known_gaps": { "type": "array", "items": { "$ref": "#/$defs/known_gap" } }
+      }
+    },
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "inputs"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "inputs": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/source_id" } }
+      }
+    },
+    "statement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "class", "proposition", "source_refs"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[0-9a-f]{16}$" },
+        "class": { "type": "string", "enum": ["observed", "deterministic_derived"] },
+        "proposition": { "type": "string", "minLength": 1 },
+        "source_refs": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/source_id" } },
+        "turn_ref": { "type": "integer", "minimum": -1 },
+        "actor": { "type": "string", "minLength": 1 },
+        "rule": { "$ref": "#/$defs/rule" }
+      },
+      "oneOf": [
+        {
+          "properties": { "class": { "const": "observed" } },
+          "required": ["class"],
+          "not": { "required": ["rule"] }
+        },
+        {
+          "properties": { "class": { "const": "deterministic_derived" } },
+          "required": ["class", "rule"]
+        }
+      ]
+    },
+    "turn": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ordinal", "sessionId", "boundary", "known_gap_refs", "statements"],
+      "properties": {
+        "ordinal": { "type": "integer", "minimum": -1 },
+        "sessionId": { "type": "string", "minLength": 1 },
+        "turnId": { "type": "string", "minLength": 1 },
+        "boundary": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["derived"],
+          "properties": {
+            "derived": { "type": "boolean" },
+            "rule_id": { "type": "string", "const": "turn-spine/v1" }
+          }
+        },
+        "purpose": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["step", "gate"],
+          "properties": {
+            "step": { "type": "string", "minLength": 1 },
+            "gate": { "type": "string", "minLength": 1 }
+          }
+        },
+        "known_gap_refs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "statements": { "type": "array", "items": { "$ref": "#/$defs/statement" } }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": { "type": "string", "const": "grounded-runtime-projection/v1" },
+    "narrative_id": { "type": "string", "minLength": 1 },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["projector", "projected_at", "manifest_sha256"],
+      "properties": {
+        "projector": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 }
+          }
+        },
+        "projected_at": { "type": "string", "format": "date-time" },
+        "manifest_sha256": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "capture_completeness": { "$ref": "#/$defs/capture_completeness" },
+    "turns": { "type": "array", "items": { "$ref": "#/$defs/turn" } },
+    "document_statements": { "type": "array", "items": { "$ref": "#/$defs/statement" } },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sources", "cited", "unavailable"],
+      "properties": {
+        "sources": { "type": "integer", "minimum": 0 },
+        "cited": { "type": "integer", "minimum": 0 },
+        "unavailable": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/narrative-source-manifest.schema.json

@@ -0,0 +1,294 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/narrative-source-manifest.schema.json",
+  "title": "Flow Agents Narrative Source Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "narrative_id",
+    "captured_at",
+    "compiler",
+    "capture_completeness",
+    "sources"
+  ],
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "chain_prev_hash": {
+      "anyOf": [
+        {
+          "const": "a3f9e2b7d5c84f1e6a0d2c3b9f7e1a4d8c6b5f2e9a0d3c7b1f4e8a2d6c0b9f3"
+        },
+        {
+          "$ref": "#/$defs/sha256"
+        }
+      ]
+    },
+    "source_id": {
+      "type": "string",
+      "pattern": "^fa1:(telemetry|cmdlog|agent-event|delegation|trust-claim|trust-evidence|flow-state|flow-report|flow-transition|surface-explanation|transcript|file):(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*:(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+(?:/(?:[A-Za-z0-9._~-]|%[0-9A-Fa-f]{2})+)*(?:#(?:0|[1-9][0-9]*))?$"
+    },
+    "integrity_class": {
+      "type": "string",
+      "enum": [
+        "hash_chained",
+        "append_only_unhashed",
+        "rotatable",
+        "overwritten_in_place",
+        "path_only"
+      ]
+    },
+    "origin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["store", "path_class"],
+      "properties": {
+        "store": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path_class": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "chain": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["seq", "prevHash", "hash"],
+          "properties": {
+            "seq": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "prevHash": {
+              "$ref": "#/$defs/chain_prev_hash"
+            },
+            "hash": {
+              "$ref": "#/$defs/sha256"
+            }
+          }
+        },
+        "package": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["name", "version"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "version": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+    "redactions": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_$-]+(?:\\.[A-Za-z0-9_$-]+)*$"
+      }
+    },
+    "lineage": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["at", "event"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "event": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "snapshotted_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_id",
+        "integrity_class",
+        "captured_at",
+        "origin",
+        "status",
+        "sha256",
+        "bytes",
+        "lineage"
+      ],
+      "properties": {
+        "source_id": {
+          "$ref": "#/$defs/source_id"
+        },
+        "integrity_class": {
+          "$ref": "#/$defs/integrity_class"
+        },
+        "captured_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "origin": {
+          "$ref": "#/$defs/origin"
+        },
+        "status": {
+          "const": "snapshotted"
+        },
+        "sha256": {
+          "$ref": "#/$defs/sha256"
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "redactions": {
+          "$ref": "#/$defs/redactions"
+        },
+        "lineage": {
+          "$ref": "#/$defs/lineage"
+        }
+      }
+    },
+    "unavailable_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "source_id",
+        "integrity_class",
+        "captured_at",
+        "origin",
+        "status",
+        "unavailable_reason",
+        "lineage"
+      ],
+      "properties": {
+        "source_id": {
+          "$ref": "#/$defs/source_id"
+        },
+        "integrity_class": {
+          "$ref": "#/$defs/integrity_class"
+        },
+        "captured_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "origin": {
+          "$ref": "#/$defs/origin"
+        },
+        "status": {
+          "const": "unavailable"
+        },
+        "unavailable_reason": {
+          "type": "string",
+          "enum": [
+            "expired",
+            "redacted",
+            "unauthorized",
+            "not_captured",
+            "corrupt"
+          ]
+        },
+        "redactions": {
+          "$ref": "#/$defs/redactions"
+        },
+        "lineage": {
+          "$ref": "#/$defs/lineage"
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "narrative_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "captured_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "compiler": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "policy_hash"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "policy_hash": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "capture_completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["channels", "known_gaps"],
+      "properties": {
+        "channels": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["active", "inactive", "unknown"]
+          }
+        },
+        "known_gaps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["class", "ref"],
+            "properties": {
+              "class": {
+                "type": "string",
+                "enum": [
+                  "mcp_non_native_tools",
+                  "actor_attribution_conflation",
+                  "cross_session_event_contamination"
+                ]
+              },
+              "ref": {
+                "type": "string",
+                "minLength": 1
+              },
+              "note": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/snapshotted_source"
+          },
+          {
+            "$ref": "#/$defs/unavailable_source"
+          }
+        ]
+      }
+    }
+  }
+}